%   This is the source for the AmigaTeX manual.  This manual is
%   (C) 1986 Radical Eye Software, All Rights Are Reserved.
%   It may not be duplicated in any form without the express
%   written permission of Tomas Rokicki or other Radical Eye
%   Software representative.
%   The fonts are 10 point fonts with halfstep magnification.
%   A few simple macros to handle sections and a table of contents:
\magnification=\magstephalf
\hsize=6truein\hoffset=0.5truein
\raggedbottom
\def\cbanner{(C) Copyright 1987 by Radical Eye Software-{-}-All Rights Reserved}
\def\banner{This is CTeX, Amiga Version 2.9c (preloaded format=plain 88.2.21)}
\newcount\secno\newcount\subsecno
\newread\tocf\newwrite\indx
\def\sec#1{\global\advance\secno by1\global\subsecno=0
\vfill\eject
\message{*\the\secno*}
\write\indx{\noexpand\t #1\noexpand\\\the\pageno\noexpand\\}
\noindent{\Bigf\number\secno.\ #1}\nobreak}
\def\sub#1{\global\advance\subsecno by1
\write\indx{\noexpand\u #1\noexpand\\\the\pageno\noexpand\\}
\par\medbreak
\noindent{\bigf\number\secno.\number\subsecno\ #1}\nobreak}
\def\toc{\secno=0
\def\leaderfill{\leaders\hbox to 1em{\hss.\hss}\hfill}
\def\t##1\\##2\\{\global\advance\secno by1\global\subsecno=0
\vb\line{{\bf\number\secno.\ ##1}\leaderfill {\bf ##2}}}
\def\u##1\\##2\\{\global\advance\subsecno by1
\vb\line{\hskip\parindent{\bf\number\secno.\number\subsecno\ ##1}\leaderfill
{\bf ##2}}}
\ct{Table of Contents}
\openin\tocf=\jobname.toc
\ifeof\tocf\message{Table of contents file nonexistent}
(none yet)\closein\tocf\else
\closein\tocf\input\jobname.toc\fi
\openout\indx\jobname.toc
\global\secno=0
\vfill\eject}
%   A few minor macros for convenience
\def\vb{\vskip\baselineskip}
\def\ct#1{\centerline{\Bigf #1}}
\def\ti#1{\leftline{\bigf #1}}
\def\AT{Amiga\TeX}
\def\.#1{\hbox{\tt #1}}
\def\\{\hskip 0pt plus 1fill minus 1in\break}
\def\cmd#1{\vb\vbox{\leftskip=\parindent\parindent=0pt\tt#1}\vb}
\def\mcmd#1{\cmd{#1}\endgroup}
\def\ttcmd{\begingroup\def\t{\strut\ \ \ }
\catcode`\^=12 \catcode`\$=12\catcode`\~=12 \def\!{\ttbackslash}\mcmd}
\def\ttbackslash{\char92}
%   The manual is outlined; each outline line is preceded by a
%   pair of percent signs to be distinguished from comments.
%   But first, the title page.
\font\Bigf=cmbx10 scaled 1577
\font\bigf=cmbx10 scaled 1315
{\null\vfil
\centerline{\Bigf \AT}
\vskip 5pt
\centerline{\bigf An Implementation of \TeX}
\vskip 2pt
\centerline{\bigf for the Amiga}
\vskip 12pt
\centerline{Version 1.5}
\message{AmigaTeX Manual, Version 1.5}
\vskip 2pt
\centerline{21 February 1988}
\vfil
\centerline{Copyright \copyright\ 1986, 1987, 1988 Radical Eye Software}
\vskip 2pt
\centerline{All Rights Reserved}
\vskip 80pt
\nopagenumbers
\eject}
%   License, use and release information
\ti{Software Licensing}
\noindent
\AT\ is not a public domain software package.  Use of \AT\
without a valid license is prohibited.  Nothing included
with \AT\ is copy-protected in any form both for the convenience
of the user
and because of the author's personal feelings on copy protection.
Copies may be made
of the components of \AT\ (which includes the programs \.{tex},
\.{initex}, \.{bibtex}, \.{preview}, \.{gftopk}, \.{pxtopk},
\.{pktype}, \.{unamiga}, and \.{set}) only as required for backup and
convenient use on a single Amiga personal computer; any further
distribution is strictly prohibited.
\ti{Manual Copyright}
%   A short message to warn the reader against printing out this
%   manual.
\message
{This manual is supplied as one of the examples for TeX on the Amiga.}
\message
{It may be used as an example TeX file; it can be run through TeX and}
\message
{displayed with the preview program.  However, it may not be printed out}
\message
{or transmitted in any form, source, dvi, or otherwise.  This manual is}
\message
{Copyright 1986-8 by Radical Eye Software, and all rights are reserved.}
\message
{ ---Tomas Rokicki, Radical Eye Software}
%   Don't forget to register this copyright!
\noindent
Copyright \copyright\ 1986, 1987, 1988 by Radical Eye Software.  All rights
are reserved.
No part of this publication may be reproduced, transmitted,
transcribed, or otherwise distributed, without the prior written
permission of Radical Eye Software.  The \TeX\ source for this
manual is stored on the distribution diskettes as one of the examples;
this does not imply the right to print it out or transmit it in any
form.
\ti{Disclaimer}
\noindent
Radical Eye Software makes no representations or warranties with
respect to the contents hereof and specifically disclaims any
implied warranties of merchantability or fitness for any particular
purpose.  Radical Eye Software reserves the right to revise this
document and the enclosed software without obligation of Radical
Eye Software to notify any person of such revision.
\ti{Trademarks}
\noindent
%   Register this trademark, and then remove this comment!
%\AT\ is a trademark of Radical Eye Software.
\TeX\ is a trademark of The American Mathematical Society.  Amiga is
a trademark of Commodore-Amiga, Inc.  Unix is a trademark of
Bell Laboratories.  IBM is a trademark of International Business
Machines.  HP and LaserJet are trademarks of Hewlett-Packard
Incorporated.  PostScript is a trademark of Adobe, Incorporated.
Dr.~Pepper is a trademark of the Dr.~Pepper Company.
\vfill
\eject
%   A table of contents
%   Now we have the introduction
%%    AmigaTeX manual outline
\null\vb\vb
\ct{\AT}
\ct{Users Manual and Installation Guide}
\vb\vb\vb\vb
Welcome to the world of \TeX\ on the Amiga.  If you have used \TeX\
on other computer systems, you will feel at home with
\AT.  If you are a newcomer to \TeX, welcome!  You will find the Amiga
to be a powerful machine on which to learn \TeX\ and develop your
documents.
We want to hear from you!  Positive comments inspire further work on
the product, and negative comments indicate a direction to proceed.
If you have any difficulty getting the package up, let us know!
It is preferred that you write to Tomas Rokicki at Box 2081, Stanford,
CA~~94309; if you must call, the telephone number is (415) 326-5312.
Do not let the complexity of the package intimidate you; if you can't
get something to work, either we haven't explained things correctly,
or there is a bug.
If this is an update of the previous release for you, you might want to
skip ahead to the `recent changes' section and simply read that.
To run \AT, you need at least 512K of RAM and at least two floppy drives,
one floppy drive and 1.5M of RAM, or one floppy and
a hard disk, and version 1.2 or later of the Amiga operating system.
Before we jump in, a few comments must be made about
conventions used in this manual.
%%   I.  Manual organization and conventions
All commands and file names will be set in typewriter type.  Commands
are separated from the accompanying text by blank lines, and
are preceded by any prompts that are not typed by the user.  For
instance, to list the size of the file \.{foo.bar}, you would
\cmd{1> list foo.bar}
\noindent
In this example, `\.{1> }' is the CLI prompt (yours may be different),
and you
would not type those letters.  (CLI stands for Command Language
Interface.)  The word \.{tex} refers to the program \TeX\
as it has been ported to the Amiga; the word \TeX\ refers to the more
general software package and typesetting language that runs on a wide
variety of machines.  Any unfamiliar terms may be looked up in the
glossary at the end of this manual.
%%   II.  First run
%%        A.  Backup the supplied disks!
\sec{First Run}
Before you run any of the supplied software or even examine the contents
of the disks, you should back them all up.  There are two ways to back
up floppies on the Amiga: using the CLI and using the workbench.
\sub{Copying Floppies Using the CLI}
If you are familiar with the CLI, the easiest way to back up floppies is
to type
\cmd{1> diskcopy df0:\ to df1:}
\noindent
The system will prompt you to insert the floppies.  Insert the original
floppy into the drive on the main system; insert a blank floppy into the
external drive, and hit carriage return.  The system should copy the
disk and give you another prompt when it is done.  If the system responds
instead with:
\cmd{1> diskcopy df0:\ to df1:\\
Unknown command diskcopy\\
\noindent
First, insure that you typed the command name correctly.  If you did, then
your system does not have a CLI diskcopy routine; so you will have to
use the following procedure for the workbench.  Even if it did work, if
you are unfamiliar with the Amiga, you might read the following description
to understand how to interact with the Amiga using the mouse, icons, and
menus.
\sub{Copying Floppies Using the Workbench}
Copying floppies using the workbench is easy, despite the length of the
following description.  Insert the original
floppy into the internal drive and a blank disk into the external drive.
After a second or two, an icon (small symbol above a name used to represent
a file or device on the amiga) should appear on the screen for both disks.
The blank disk might have an icon with the name \.{DF1:BAD}. Don't let that
worry you. The floppy is simply unformatted, and the diskcopy operation will
format it as it copies.  Now, using the mouse, move the arrow until its tip
is over the icon representing the original disk.  Hold down the left mouse
button (the select button) and `drag' that icon until it rests on top of
the icon for the blank disk.  Now release the select button.
The machine might now prompt you to replace the workbench floppy into any
drive.  The prompt is called a `requester' because it requests something
from the user before the operation can proceed.  In this case, it
needs to load the diskcopy program into memory,
and that program resides on the workbench disk.  Remove the floppy from
the internal drive and re-insert the workbench floppy.  After a few
seconds, the system will prompt you to replace the disk from which you are
copying
into the internal drive.  Remove the workbench floppy and re-insert
the disk it replaced.
{\bf NEVER REMOVE A DISKETTE WHILE THE DRIVE LIGHT IS ON.  This can
destroy any data on the floppy.  Even when the system puts up a
requester, wait until the drive light goes out before removing the
floppy.  This is important; you might consider re-reading
this paragraph.}
If everything went as it should, you should now have another requester
on the screen titled \.{Disk Copy}.  Move the mouse pointer over the
{\it Continue\/} option, and hit the select button.  The copy operation
should start and finish a few minutes later.  You have just backed
up a floppy.  Remember this operation; you should use it often to
guard against bad floppies, electrical storms, and three-year-old
popsicle eaters.
We are not done yet.  If you look at the icons on the workbench,
you will notice that the new floppy is called \.{copy of foo.bar} if
the original disk was called \.{foo.bar}.  If you are making copies of
the distribution floppies from which to work, this name will not do,
since \AT\ will often request a specific floppy by name.  Therefore,
you will need to rename the floppy.  To do this, move the mouse pointer
over the icon for the new copy, and press and release the select button.
The icon should turn from white to black.  Now hold down the right
mouse button (the menu button).  The title bar on the workbench should
change to show \.{Workbench}, \.{Disk}, and \.{Special}.  Move the
pointer (still holding down the menu button) over the word \.{Workbench}.
A menu should appear.
Now, still holding the menu button down, drag the mouse pointer down
until it is over the word \.{Rename}, and release the menu button.
This is how menu selections are made on the Amiga.  A thin box should
appear in the middle of the screen with the name of the selected icon
in it.  (If you are using version 1.1 of the operating system, you
will need to move the mouse pointer until it lies within this box, and
hit the select button.  Anything you type before this will be ignored.)
Now, simply hit the {\it DEL\/} key on the keyboard (in the upper right)
eight times, until \.{copy of} disappears and the cursor is on top of
the first character of the original name.  Now hit the {\it RETURN\/}
key, and the name of the icon should change.
Appropriatel label the new copy you just made, with a paper floppy
label, put the original disk away in a safe place, and repeat for all of
the distribution floppies.
%%        B.  Set the Amiga to 80-column mode, CLI on
\sub{Setting up Preferences for \AT}
\AT\ must be run in the 80-column mode and using CLI.  If this is not
how your system is configured, or you are not sure, you should go into
preferences.
To go into preferences from CLI, type
\cmd{1> df0:preferences}
From the workbench, move the pointer over the \.{workbench} icon, and
double click (hit the select button twice rapidly).  Next, double-click
over the \.{Preferences} icon that should appear inside the workbench
window.  Your screen should change into the \.{Preferences} screen.
Look in the middle of the left side of the screen; you should see the
words \.{Text} and \.{CLI}, each with two little boxes to the left
of them.  The selected box should be \.{80}
for \.{Text}, and \.{On} for \.{CLI}.  If they are not set correctly,
simply select the appropriate box with the mouse and select button.
If they needed changing, you now need to select the \.{Save} option
in the lower right corner of the screen and reboot; if the options were
correct, you can select the \.{Cancel} option.
To reboot, simply hold down the {\it CTRL} key (middle left of the keyboard)
and the two Amiga keys (fancy `A' keys on either side of the space bar) at
the same time.
%%        D.  Get in a CLI, open to full width of screen
\sub{Getting Into a CLI}
Now you need to get a CLI window to work with.  If you already have
opened a CLI, fine; you are in good shape.  Otherwise, the following
procedure will open a CLI window for you.
Double click on the \.{workbench} icon if the \.{workbench} window
is not already open.  Within the \.{workbench} window, you should
see an icon labeled \.{CLI}.  If you don't see this icon, double
click on the \.{system} icon to open its window; the \.{CLI} icon
should be in this window.  If it is not, check preferences again
to insure that the \.{CLI} has been turned on.  If all else fails,
reboot, and when the screen first turns blue, hold down the
{\it CNTRL\/} key and hit the `d' key until the word {\it BREAK\/}
appears.  Now you are in a CLI.
If the CLI you are in does not extend to the full width of the
screen, you will need to resize it.  This is done by first selecting
the title bar of the CLI window (where the word \.{CLI} or \.{AmigaDOS}
is) and dragging the whole window until it is flush with the left of
the screen.  Next, select the sizing gadget in the lower right of the
window, and drag it until it is flush with the right of the screen.
%%	 Stack requirements
\sub{Stack requirements for \AT}
\AT\ requires more stack space than is provided by default on the Amiga.
This is also true of a lot of other programs for the Amiga, so this
paragraph may cure some problems you may have been having on your system.
In the CLI window you created, type
\cmd{1> stack}
\noindent
If the number displayed is 4000, then you need to set your stack to a
larger value.  To do this at the command line, simply type
\cmd{1> stack 10240}
\noindent
This is sufficient for almost all programs.  If another application
requires a larger stack, you should increase that number.  Note that
in general, this command should go into your \.{s:startup-sequence}
file.
%%        C.  512K system?  Move some files around.
\sub{Setting Up a 512K System}
If your Amiga has 512K of RAM, you will need to make some changes to
the supplied disk to start.  Before you read any further, make sure
that you have backed up the distribution diskettes, and are working
from your own copies.  The following step, if run on the distribution
floppies, will destroy a file that you will need if you ever get more
memory.  With that caveat, please continue.
To set up \AT\ for a 512K system, insert the floppy
labeled \.{TeX} into the external drive.  From the CLI,
\cmd{1> execute tex:s/to-512}
(Note that the Amiga is case insensitive; upper and lower case in file
names are equivalent.  Thus, though the floppy is really named
\.{TeX}, it can be referred to as \.{tex}.)  After a few
seconds, it should prompt you to insert the disk labeled \.{TeXfiles}
into the internal drive,
and then to reinsert the workbench disk.  After the operation is
complete and the floppy drive lights have gone out, reboot the
machine.
%%        E.  Run TeX on samples/story.tex
\sub{Running \TeX}
Now you are ready to run \TeX.  If you are ambitious and familiar with
\TeX, you may choose to prepare a short sample file at this time.
For those not familiar with \TeX\ and for those in a hurry, we have
prepared a few sample files.  At this point, you should be at a CLI
prompt.  Insert the disk labeled \.{TeXfiles} into your external
drive, and type
\cmd{1> texfiles:c/tex}
The disk will grind for a while, and then a requester for the floppy
labeled \.{TeX} will appear.  Remove the \.{TeXfiles} floppy and insert
the \.{TeX} floppy in its place.  After a few seconds, \TeX\ should
appear with the following hello:
\cmd{\cbanner\\
\banner\\
\noindent
If instead you get the message
\cmd{Out of memory during allocation!}
\noindent
then there are several possibilities.  If you are running on a system
with more than 512K of RAM, you must have too many things in memory
at the moment.  Shut down some other programs and try again.  Or possibly
you have not told the system about your extra memory; the Amiga 1.1
operating system does not automatically recognize expansion memory, and
some memory boards are not recognized under 1.2.  Amiga\TeX\ requires
the 1.2 operating system.  Consult
the documentation supplied with your memory boards.  If you are running
on a 512K system, perhaps you didn't follow the above instructions that
pertain to you.  Alternatively, you might have some files in RAM disk.
Try rebooting.
The double asterisk (\.{**}, also referred to as double splat) prompt is
\TeX's way of asking you for a file name.  Type your own file name if
you have prepared a file, or type
\cmd{**story}
\noindent
if not.  There will be a pause of approximately five seconds, after which
the screen should look like this:
\cmd{\cbanner\\
\banner\\
**story\\
(tex:inputs/story.tex [1])\\
The single asterisk prompt indicates that it is finished, and is waiting
for more commands.  At this point, simply type
\cmd{*\ttbackslash bye}
A few more seconds should go by, and then \TeX\ should reappear with
another double splat prompt.  This is because of the `loop mode' that
will be explained later.  For now, just hold down the {\it CNTRL\/} key
and press the `F' to get the CLI prompt back.  Congratulations!
You have just finished your first \TeX\ job on the Amiga!
%%        F.  Run preview on story
\sub{Running Preview}
Now you are probably anxious to see what the output looks like.  To
see, insert the \.{TeXfiles} disk into the external drive, and type
\cmd{texfiles:c/preview story}
\noindent
Wait for the external drive light to go out, and insert the \.{TeX}
disk.  Your file
should appear on the screen.  If you are ambitious, you might try
figuring out how to work the preview program at this point, using what
you know about gadgets and menus.  Otherwise, you can exit the program
by selecting the square gadget in the upper left corner of the screen
with the select button, or simply by hitting the `Q' key on the keyboard.
If all else fails, reboot and read further.
Do not be discouraged by the apparent awkwardness of this process.
Setting up an interactive, multitasking \TeX\ environment is described
later.  You might care to take a breather here, so you can enjoy the
descriptions of \TeX\ and the Amiga which follow.
%%   III.  What is TeX?
%%         A.  Purpose
\sec{What is \TeX?}
\TeX\ is a typesetting language and system developed by Professor
Donald Knuth of Stanford University over the period 1977 to 1986.
It was designed to be used in typesetting books and manuscripts,
especially those containing much mathematics.
The current version of
the language has been stable since 1982, and is currently in use
at thousands of computer installations all over the world.
%%         B.  User interface
The input to \TeX\ is somewhat free format; it is emphatically not
a \hbox{WYSIWYG} (what you see is what you get, often rephrased as what you
see is all you get) system.  The source can be created with any typical
text editor, and for the most part spacing and line breaks in the input
are ignored.  Interspersed with the text are various typesetting
commands that might, for instance, change fonts or skip to the next
page.  \TeX\ is programmable with paramaterized macros and user variables
of a number of types, allowing the creation of macro packages that
extend the power of \TeX\ or make it more accessible.
\TeX\ is not the solution to all the world's ills.  As a document
preparation system, it has three major deficiencies.  First, it does
not directly support graphics.  You can use horizontal and vertical
rules, and do some limited graphics using a variety of methods: La\TeX\
supports some graphics operations, and most PostScript printer drivers
allow inclusion of graphics commands.  Secondly, \TeX\ does not easily
do complicated page layout, as might be required for newspapers, for
instance.  And finally, \TeX\ does not allow interactive editing
and viewing of the document as it is being developed.
All of these are design decisions; \TeX\ was never intended to address
any of these concerns.  What \TeX\ does, however, \TeX\ does well.
It supports a huge library of fonts, and additional fonts can be
purchased from a number of companies.  It supports full kerning and
ligatures in its fonts.  It has no equal when typesetting
complicated mathematical formulas and displays.  Its hyphenation
algorithm is among the best in typesetting systems, and its line-
and page-breaking algorithms are nothing short of incredible.
\TeX\ is a complicated system, because typesetting is not a simple
task.  It is easy to generate quality documents without knowing
much about \TeX, but as your experience and requirements grow, you
will find that \TeX\ has the power, programmability and expandability
to handle your most demanding needs.
%%         C.  Device and computer independence
One of the primary objectives of Knuth in writing \TeX\ was computer and
printer independence; the output you display on your Amiga screen should
appear (within the resolution limits of the device) exactly the same as
the output on the professional typesetting equipment of Addison-Wesley,
for instance.  The same source should work and generate identical output
on all computer installations that run \TeX.
%%         D.  Processing; explanation of file types
To illustrate \TeX, the processing of our sample \.{story.tex} above is
going to be examined, and each file used by \TeX\ in the creation of
the document will be explained.
The source was typed in by hand from the first example
in {\it The \TeX book,} page 24, and as all source files for \TeX\ should,
it has the extension \.{.tex}.
Some of the commands used in \.{story.tex} are not a part of primitive
\TeX; primitive \TeX\ is very primitive indeed.  Therefore,
\TeX\ by default loads a set of macros called `plain \TeX' into memory.
Rather than load these macros in as \TeX\ source (which it could), it
instead loads them in a pre-digested form called a `format file', with
the extension \.{.fmt}.  This \.{plain.fmt} file contains essentially a
memory image of \TeX\ after all of the macros in plain \TeX are loaded.
Primitive \TeX\ does not know any characteristics of any fonts, either.
Therefore, a number of font metric files with the extension \.{.tfm}
were loaded while the \.{plain.fmt} file was created.  These files contain
information about individual characters in the font and the font as a
whole, such as the height, width, and depth of each character, what
ligatures the font contains, and what kerning is necessary between
which characters.  There is one of these files for each font accessible
to \TeX, and they contain only information about the fonts that is
independent of the output device.
As \TeX\ was processing \.{story.tex}, it created two files, one with
the extension \.{.log} and one with the extension \.{.dvi}.  The log file
contains essentially a listing of the run as it was seen from the terminal,
including any error messages that were displayed.  This file is useful if
an error message was too long and scrolled off the display, for instance;
various switches can also be turned on inside \TeX\ to display more
information about what is happening during the typesetting process.
The main output file of \TeX\ is the device-independent file, with the
extension \.{.dvi}.  This file contains a description of the final
document, including the location and font of each character used.
The units used in this file are not based on any particular device, and
the actual characters themselves are not described.  It is up to another
program, the `driver', to interpret this \.{.dvi} file, look up the
appropriate raster representations of the individual characters, and
create the final document.
The preview program is one such program.  It `drives' the Amiga screen,
loading font raster information from a collection of packed, or \.{.pk},
files.  There is one of these files for each font at each size, since
the raster description of a character is by its very nature dependent
on the resolution of the output device.
%%         E.  Reference to TeXbook, LaTeXbook
This was intended to be a simple description of \TeX; for more
information, please refer to {\it The \TeX book\/} by Donald Knuth and
{\it La\TeX\ User's Guide and Reference Manual\/} by Leslie Lamport,
both published by Addison-Wesley Publishing Company and available in
most college bookstores.
\sec{Introduction to the Amiga}
The Amiga is an impressive computer system that is well suited to
\TeX\ for a number of reasons.  The high-resolution graphics built
into the machine allow high-quality preview of the output.
Multitasking and a large memory capacity allow the editor, previewer,
\TeX, and even other programs to be concurrently resident and active,
yielding a much more interactive environment than is possible on
any other microcomputer.  Intuition, the Amiga windowing software,
ties these and other packages together into a unified, convenient,
natural interface for the user.
The section title is somewhat of a misnomer, since if you have run
the sample, you are probably familiar with the Amiga by this
time.  Nonetheless, there are a few things that have not been covered
%%   IV.  Introduction to the Amiga
%%        A.  Mouse
%%        B.  Gadgets
The mouse is the primary input device for the Amiga.  The point and
click approach is easy to master.  The Amiga mouse has two buttons,
the select button on the left and the menu button on the right.
The select button is used for selecting data, operations, windows;
the menu button is used to select among a number of alternative
actions or settings.  Gadgets are graphic images that are associated
with a particular action; moving the mouse pointer over them and
clicking the select button starts the operation.  Note that for most
gadgets, the mouse must remain over the gadget while the button is both
pushed and released; it is the release on the gadget that actually
signals the operation to begin.
%%        E.  Menus
Menu items are selected by pressing and holding the right mouse
button as the pointer is moved first to the title bar to select
the particular menu, and then down the menu (and possible sub-menus)
until the appropriate action is found.  It is the release of the
menu button that starts the operation.
Windows and screens help separate the input and output of programs
from one another, and to bring to display the information currently
being worked with and hide irrelevant data.  Screens occupy the full
width of the video display and can only be dragged up and down.
A typical screen is the workbench screen.  Windows reside in screens,
and can be an arbitrary rectangular portion of a screen.  A window
cannot be moved from screen to screen; once created, it is
permanently associated with a particular screen.  A window can be
moved horizontally or vertically so long as it remains on the screen.
A window inherits the video characteristics of a screen, but each screen
can have its own characteristics.  For instance, the workbench screen is
a four-color high-resolution non-interlace screen; the preview screen is
a two-color high-resolution interlace or non-interlace screen.  Many
graphics programs run in a 32-color low-resolution non-interlace screen.
At any given time, either zero or one window is active.  A screen is
only `active' if a window on that screen is active.  Inactive windows
have their title bar cross-hatched over to indicate their status;
the active window does not have this cross-hatch pattern.  To
select a window, you simply place the pointer inside that window and
hit the select button.
%%        C.  Screens
%%        D.  Windows
To drag a window or a screen, select the title bar and move the mouse
with the select button held down.  A screen will move as the mouse
moves; for a window, an orange outline of the window will move, and
when the mouse stops moving, the window will be redrawn in its new
position.  The two gadgets in the upper right hand corner of a window
or screen are the to-front and to-back gadgets; selecting the
right-most gadget (to-front) brings the corresponding window or screen
in front of all other window or screens, selecting its neighbor (to-back)
pushes it in back of all others.  Note that a window might cover the
screen's to-front and to-back gadgets; full-sized CLI windows are typical
culprits.  You probably want to resize a full-sized CLI window to make it
slightly shorter, and then drag it down a bit to expose the screen gadgets;
otherwise, you cannot move among the various screens easily.
Windows usually have a sizing gadget in the lower right hand corner.
This is used to change the size of a window; simply select and drag it.
They also usually have a close gadget in the upper left hand corner;
selecting this gadget terminates the program running in the window.
Menus are associated with the active window, but are displayed on the
screen title bar.  Thus, one screen might have many possible menus,
depending on which window is the active one.
An icon is a graphics image that represents a file or device.
On the workbench screen, for instance, there is an icon for each
disk.  Files may or may not have an icon associated with them; currently,
the \AT\ system does not use icons.  Icons are selected with the select
button; they are activated (if a program, it is run; if a directory, it
is opened) by double-clicking on them.
%%        F.  CLI
%%        G.  Multitasking
%%        H.  Never punch out disk while light is on
Another nice feature of the Amiga is that it doesn't restrict
you to use the desktop metaphor (icons, menus and windows); you are
free to use the more conventional CLI, or command language interface,
under which you type commands with the keyboard.  This is the primary
environment \AT\ runs in.  The Amiga CLI is a simple shell to
the underlying TRIPOS-based operating system.  As with any command-based
interface, there are commands and conventions that must be learned.
For instance, \.{cd} changes the current working directory; \.{dir}
displays the names of all of the files in that directory, and
\.{type} displays the contents of a file.  For a description of these
commands, refer to the {\it AmigaDOS User's Manual\/} published by
Addison-Wesley, available where you purchased your Amiga.
If your Amiga makes annoying clicking noises every second or so, it is
because your disk drives do not have floppies in them; insert blank
floppies into the disk drives when not in use to keep the Amiga happy.
%%   V.  Installation instructions
\sec{Installation}
Now you are ready to install \AT\ onto your system.  The next few sections
each pertain to a certain part of the installation; read only those sections
that pertain to you.
%%       A.  512K system?  Move files
\sub{Installation on a 512K System}
\AT\ will run on a 512K system, but you will not be able to take full
advantage of the package without additional memory.  Normally \TeX\ alone
requires 700K of RAM.  In order to run \TeX\ on a 512K machine, several
restrictions must be observed.  The RAM disk cannot be used or even created.
Note that any reference to the RAM disk will create it if it does not
exist.  To see if it exists, simply type
\cmd{1> info}
\noindent
If it exists, it will be listed as a mounted disk, and you must reboot
before you can run \AT.  No other applications can be run at the same
time as \AT; it needs all of the memory in the machine.  La\TeX\ and other
extensive macro packages cannot be run.  Even with these restrictions,
it is quite possible that you will eventually create a document that
\AT\ cannot process because it runs out of memory internally.  However,
most typical documents should present little difficulty; \AT\ itself and
this manual were both fully developed and run on a 512K Amiga.
%%           1.  Procedure
The version of \AT\ that runs on a 512K system is identical to the
version that runs on a larger system, but the format files are different
because of the different array sizes.  In addition, a special file must
be installed that informs \TeX\ of the sizes to make its internal arrays.
Make sure that you have followed the procedure outlined in {\bf 1.5} above to
move the files to their correct places.
%%           2.  Upgrade procedure when you get more memory
If you later get more memory and wish to use the full power of \AT, you
will need to re-install the original format file.  To do this, simply
make a fresh backup copy of the first distribution diskette and use it
instead of the \.{TeX} disk you used with 512K.
%%       B.  Floppy system?
\sub{Installation on a Dual-Floppy System}
\AT\ runs comfortably on two floppies.  The floppy that resides in the
internal drive is the workbench
floppy and contains all of the files for the Amiga operating system and
all of your personal \TeX\ files.  The floppy in the external drive
contains all of the
files \TeX\ requires to run, including the font metric, format, and packed
raster files.  This second floppy must be labeled `\.{TeX}' and is usually just
a copy of floppy one of the distribution.
%%           1.  Make TeX workbench
Usually the workbench floppies as supplied with the Amiga are very full,
restricting the amount of working file space for your \TeX\ files.
There are a lot of files on the workbench that are not used much, though,
and can be deleted to make more space.  This is a list of some of the
files and directories on the distribution floppy that can be deleted, in
order from largest to smallest.  The colon on the front of each name
indicates the root directory of the floppy.  To delete an entire
directory and its contents, type
\cmd{1> delete :fonts all}
\noindent
to delete the fonts directory and all of the files in it.  To delete only
a file or two, type
\cmd{1> delete :Preferences :Preferences.info}
\noindent
Note that you can specify a maximum of ten files to the delete command.
To list the contents of a directory, type
\cmd{1> list :Utilities}
{\tt :Utilities}~~This directory contains two programs, a calculator, and
a notepad, totalling some 72K.  If you never use either program, delete
the entire directory; otherwise, just delete whichever program you don't
use.  The associated \.{.info} files can go as well.
{\tt :devs/printers}~~In this directory is a driver for all of the printers
the Amiga supports, totalling 54K.  After selecting your printer type
with preferences,
delete all of the drivers you don't use.  For instance, if you are using
an HP LaserJet, delete all of the files in this directory except
\.{hp\_laserjet}.  If you don't have a printer, you might want to delete
the entire directory.
{\tt :Preferences}~~This program is used to configure the
system to your tastes and hardware, but is 52K huge.  After becoming
comfortable with the Amiga and tweaking all of the knobs this program
has, you might want to delete it.  If you choose to run preferences at
a later date, you can simply insert another workbench floppy with preferences
intact into the external drive, and type
\cmd{1> df1:preferences}
{\tt :libs/translator.library, :devs/narrator.device, :c/say}
(and {\tt :system/say} under 1.2)~~Three files
that total 43K give your Amiga the amazing capacity of speech.
Luckily, the Amiga is easier to shut up than most people are.
{\tt :fonts}~~This directory contains several different fonts that the Amiga
can use.  Since \AT\ uses its own set of fonts, and the default system
fonts are built into the hardware, you can feel free to delete all 40K
in this directory.
{\tt :c/edit, :c/ed}~~Most people need only one editor, and usually choose to
use a commercial editor rather than the supplied Amiga editors.  Either one
or both of these files can be deleted, saving you about 19K apiece.  You
might wander around in the \.{:c} directory looking for other, unfamiliar
commands to delete as well.  A minimum subset might be \.{run}, \.{dir},
\.{list}, \.{delete}, \.{copy}, \.{execute}, \.{diskcopy}, \.{rename},
\.{cd}, \.{date}, \.{makedir}, \.{echo}, \.{endcli}, \.{newcli}, \.{type},
and \.{stack}.  In addition, under 1.2, \.{:system} contains several
cute programs you might not need.
{\tt :system/iconed}~~This is a great program to play
with; it allows you to redefine the imagery of an icon.  On a typesetting
system, however, it has little use.  This gem uses 34K.
{\tt :demos}~~This directory has a few cute demonstrations of the Amiga's
graphics abilities.  Once you are finished impressing your friends, wipe
all 20K.
{\tt :Clock}~~This is another neat program that you may never
use; deleting it reclaims 17K.
There are other things you can delete on the workbench, but these are the
major ones.  The above instructions can free up approximately 370K of
disk space to be used for \AT.  What do you do with all this space?
Well, the first thing you should probably do is copy the \.{set} and
\.{preview} programs to the workbench by inserting the \.{TeXfiles}
floppy into the external drive and typing
\cmd{1> copy texfiles:c/set c:\\
1> copy texfiles:c/preview c:}
\noindent
%%           2.  Putting or not putting TeX on WB disk
You might also want to copy the actual \.{tex} program itself with the
command
\cmd{1> copy texfiles:c/tex c:}
\noindent
The \.{tex} program is approximately 129K, though, so it will put a large
dent in the available disk space.  The advantage of placing \.{tex} on the
workbench disk is that you can invoke \.{tex} simply by typing
\cmd{1> tex}
\noindent
The alternative, if you don't copy \.{tex} to the workbench disk, is to
insert the \.{TeXfiles} floppy into the external drive, and type
\cmd{1> texfiles:c/tex}
\noindent
On a 512K system, since \TeX\ cannot run with other programs, each time
you invoke \TeX, you will need to repeat this command and swap the \.{TeXfiles}
and \.{TeX} floppies.  On a system with more memory, this needs to be done only
once, since \AT\ will stay resident using the loop mode described below.
%%       C.  Hard disk system?
\sub{Installation on a Hard Disk System}
On a hard disk system, \AT\ really shines.  To install it, first insert
the \.{TeXfiles} directory into the external drive, and type
\cmd{1> copy texfiles:c/tex c:\\
1> copy texfiles:c/preview c:\\
1> copy texfiles:c/set c:}
\noindent
Next, create a directory on the hard disk named \.{TeX}, by
\cmd{1> makedir dh0:TeX}
\noindent
(replacing \.{dh0:} with the actual device name of your hard disk.)
Now insert the \.{TeX} floppy into the external drive, and type
\cmd{1> copy tex:\ dh0:tex all}
%%           1.  Make directories
%%           2.  Install what is necessary
\noindent
This will copy the entire contents of the floppy onto the hard disk,
and it will take several minutes.  You might go get a Dr.~Pepper while
it is running, and relax.  Before running \AT\ on the hard disk, you
should type
\cmd{1> assign tex:\ dh0:tex}
\noindent
to tell \AT\ where to find the files.  When you type this command, the
\.{TeX} floppy should not be in either drive, because the system might
get confused as to what \.{tex:} refers to.  If you are familiar with
the \.{s:startup-sequence} file, that is a good place for this command.
%%       D.  Sample startup-sequence file
\sub{Running \AT}
Now everything should be in place to run \AT.
A few scenarios for running \AT\ from a cold boot will be
illustrated, so you might want to reboot at this point.
If you are running on a 512K system with two floppies, you will need to
run the editor, previewer, and \TeX\ separately.  To run \TeX, you will
either type
\cmd{1> tex}
\noindent
(if you installed \.{tex} on the workbench disk)
or insert the \.{TeXfiles} floppy into the external drive and type
\cmd{1> texfiles:c/tex}
\noindent
In either case, insert the \.{TeX} disk into the external drive when prompted
for it.  To exit from \TeX at any time, you simply need to hit
{\it CNTRL\/}-F.
If you are running on a machine with more memory, you can load \TeX, the
editor, and the previewer all into memory at the same time and switch
among them quickly and easily.  If you are using a hard disk, you
might need to type
\cmd{1> assign tex:\ dh0:tex}
\noindent
before you run \.{tex} or \.{preview}.
At this point, you are ready to open a window
for each program you will run.  Type the following command to the CLI:
\cmd{1> execute tex:s/openwindows}
\noindent
Three new CLI windows should open on top of the one you are currently
running.  They should be labeled \.{TeX}, \.{preview}, and \.{edit}
respectively.  First, select the \.{edit} window, and invoke your favorite
editor from it.  For example, you might type
\cmd{1> ed myfile.tex}
\noindent
After the editor comes up, select the \.{tex} window (you may have to hide
the editor screen or window to expose the \.{tex} window) and type
\cmd{1> tex}
\noindent
to invoke \TeX.  If you are prompted for the \.{TeX} floppy, insert it.
Wait for the \TeX\ prompt.  Next, select the \.{preview} window, and type
\cmd{1> preview}
\noindent
to bring up the previewer.  Congratulations!  You are running all three
programs simultaneously!  Practice switching back and forth among the
windows and screens; you will be doing this a lot.  You might move the
windows or screens around to suit your tastes.
Note the instructions to wait until the disks stop before typing the
next command.  This is because under the 1.2 version of the operating
system, if two files are being accessed off the same floppy simultaneously,
the system slows down to a crawl while the disk head seeks back and forth.
%%       E.  Caveat about the run command
Another caveat is appropriate here.  Another way to run multiple programs
at the same time is to invoke them with the \.{run} command, rather than to
open a new CLI window for each program.
The \.{run} command automatically lowers the priority of the program it is
running, and this can keep it from getting any processor
time.  Use \.{run} with care.
A final digression.  At this point, the screen might be flickering
because the \.{preview} program is running in interlace mode.  To
eliminate this shaking, bring the preview screen to front and select
(click inside) its screen.  Select the \.{non-interlace} option in the
\.{Modes} menu, and the flicker should go away.  Now you can comfortably
continue.
\sec{Using \TeX}
%%   VI.  Using TeX
%%        A.  Same as on any mainframe
True to the spirit of computer independence, which is an integral idea
in \TeX, the \AT\ implementation performs exactly as any other port
of \TeX.  If you invoke \AT\ with a file name given on the command
line, it will process that file and return with a prompt.  For example,
to process the file \.{tex:inputs/story}, the user dialog would appear
as follows:
\cmd{1> tex story\\
\cbanner\\
\banner\\
(tex:inputs/story.tex [1])\\
*\ttbackslash bye\\
Output written on story.dvi (1 page, 672 bytes).\\
Transcript written on story.log.\\
\noindent
The user typed only the original command line and \.{\ttbackslash bye};
the remaining output is from \TeX.
Often when running \TeX, you may find yourself wanting to exit from
it for various reasons.  \AT\ supports four levels of interrupts for
this purpose, ranging from the normal {\it CNTRL}-C which \TeX\ traps,
to an emergency {\it CNTRL}-F which aborts immediately.
While \AT\ is running over a file and not waiting for user input,
the user can type {\it CNTRL}-C.  \AT\ will respond with a \.{? }
prompt.  The user can now type `x' to exit, `i' to insert some
tokens, or `h' for further help.  Typing {\it CNTRL}-D instead of
{\it CNTRL}-C automatically types the `x' for the user, exiting.
If loop mode is being used, the format file will be reloaded, and
a new double asterisk prompt displayed.
It is possible to get \AT\ into a mode in which it does not respond
to such interrupts.  In this case, typing {\it CNTRL}-E should suffice.
This interrupt does not exit loop mode, however; {\it CNTRL}-F is
required for that.  These are even useful when \TeX\ is displaying a
prompt waiting for further input.
These last two interrupts should be used with some care.  They may
leave a malformed \.{dvi} file around; the previous two interrupts will
never do this.
%%        B.  Loop mode special for Amiga
\sub{The Amiga Loop Mode}
A significant part of the time spent processing \.{story} was spent
loading the \.{tex} executable into memory.  To help eliminate this
wasted time, \AT\ runs in a loop if it is not given a file name on
the Amiga.  For instance, if we had wanted to process \.{story.tex}
but leave \TeX\ in memory for the next time we needed it, we could
have simply typed
\cmd{1> tex\\
\cbanner\\
\banner\\
**story\\
(tex:inputs/story.tex [1])\\
*\ttbackslash bye\\
Output written on story.dvi (1 page, 672 bytes).\\
Transcript written on story.log.\\
\banner\\
\noindent
Note that this time, the banner message and double splat prompt returned,
waiting for the name of the next file we want \TeX\ to process.  It will
continue to wait patiently as you preview the output from the previous run
and make any changes to the editor source, after which you can simply
retype the name of the file to run \TeX\ again.
There is an even simpler way to run the same document again.  Simply hit
carriage return at the double splat prompt.  Amiga\TeX\ remembers what
your last file name was (or any command, typed to the double splat prompt)
so a simple carriage return will suffice.
If you want to run \TeX\ in the loop mode and give it the name of the first
file to process, you can do that with the \.{-r} option, as follows:
\cmd{1> tex -r story\\
\cbanner\\
\banner\\
(tex:inputs/story.tex [1])\\
*\ttbackslash bye\\
Output written on story.dvi (1 page, 672 bytes).\\
Transcript written on story.log.\\
\banner\\
\sub{Memory Fragmentation}
On almost any system, after a period of extended use, memory can become
fragmented.  Some of the symptoms of fragmented memory include windows
that refuse to resize or move or the refusal of \AT\ to run with the message
\cmd{Out of memory during allocation!}
\noindent
If this occurs, there is little you can do.  You might try closing
down some programs you are running and selecting `release memory' in the
project menu of the previewer first.  If this does not work, you will have
to reboot.
The loop mode of \TeX\ helps to reduce system memory fragmentation by grabbing
the memory \TeX\ needs once, and then never releasing it until you exit the
loop.  For this reason, and to reduce the amount of time it takes \TeX\ to
start, it is recommended that you use the loop mode if you have more than a
megabyte of RAM.
%%        D.  Do not write file while TeX is reading it
\sub{Writing and Reading the Same File}
The editor creates the source file, with the extension \.{.tex}.  This
file is read by \TeX, which writes a \.{.dvi} file, which is then read
by the preview program and displayed on the screen.  There are
restrictions on reading and writing a file at the same time, however;
chaos can easily result.  Therefore, it is not wise to ask the editor
to update or write out the source file while \TeX\ is processing it.
The same restrictions apply to the previewer; you must close the file
with the `close file' option of the project menu or by hitting the `C'
key while the previewer window is selected before running \TeX\
again.
If you violate this restriction, the editor might complain that it
cannot write your file, or \TeX\ might complain that it cannot write
the \.{.dvi} file.  If the editor complains, finish running \TeX, and
then reexecute the save-file command from the editor.  If \TeX\ complains,
close the file from the previewer and type the name of the\.{.dvi} file
again.
%%        C.  set options
\sub{The Null Source File}
When \TeX\ gives you the double splat prompt, it is requesting a file
name to process.  If it can't find the file you specify, it says so,
and asks for another name.
\cmd{1> tex\\
\banner\\
**lksaj\\
! I can't find file `lksaj.tex'.\\
<*> lksaj
\vb\noindent
Please type another input file name:}
\noindent
Sometime you may decide that you don't want
to process a file at that point, but it keeps giving you this annoying
error message.  There are two ways to get out of the loop; hit the abort
character ({\it CNTRL\/}-F), which gives you a fatal
error and \TeX\ exits, or simply give it the name \.{nul}, which exists
in the \.{tex:inputs} directory.  \TeX\ will then respond with a single
asterisk prompt, at which point you can type \.{\ttbackslash bye} or
\.{\ttbackslash end} to exit.
\sub{The Quick Loop Mode}
In the loop mode above, you may have noticed that each time \AT\
printed its banner line, it accessed the floppy for a while before
printing the double asterisk prompt.  It used this time to
reinitialize itself with the \.{plain.fmt} file.  If you have more
than 512K of memory, there is a way to eliminate this annoying delay.
If you invoke \AT\ with a \.{-R} option (that's capital \.{R}, not
little \.{r}) then it will save away the parts of the format file that
it needs to reload in memory.  Subsequent times around the loop, it
will simply copy this information from its internal copy, rather than
loading it from the floppy.  This requires less memory than copying the
entire format file to the ram disk because portions of the format file
do not need to be read again.  In addition, it is faster.
\sub{Amiga Special Characters}
This release of \AT\ supports most of the Amiga special characters.
These are the characters accessed through foreign keymaps, or using the
`ALT' key.  For instance, with the standard US keymap supplied with the
Amiga, if you type `ALT'-K followed by `u', you will get the character
\"u.  (Not all editors support these characters.)  With \AT, these
characters are recognized and automatically transformed into the appropriate
\TeX\ macros (in this case, `{\tt\ttbackslash"u}'.  All of the special
characters that have a correspondence within \TeX\ are supported.  The
characters that are not supported are translated into question marks.
Unfortunately, this feature adds some amount of incompatibility between
\AT\ and other \TeX\ implementations, since the other implementations do
not support these special characters.  For this reason, a program called
\.{unamiga} is supplied, which will perform the identical transform that
\TeX\ is using on an Amiga text file, created a standard ASCII file that
can be uploaded and run through other \TeX's.  To use this program, you
would type, for instance,
\cmd{1> unamiga myfile.tex toupload.tex}
\noindent
This command will take the file \.{myfile.tex}, complete with Amiga special
characters, and create a file called \.{toupload.tex}.  This second file
will be identical with the original, except the special characters will be
replaced with their \TeX\ macro equivalent.
You cannot use these special characters in file names or macro names
within \TeX.  In addition, because the translation is fixed, if you
redefine some of the accents, you may not get what you expected.  For
instance, the character `\"\i' is translated into `{\tt\ttbackslash
"\ttbackslash i}', so if you redefine {\tt\ttbackslash i}, this character
will no longer work.
The umulauts are by default the German umulauts.  If you need Hungarian
umulauts, you should use a command such as
\cmd{\ttbackslash let\ttbackslash"=\ttbackslash H}
\noindent
at the beginning of your \TeX\ document.
\sub{Amiga Environment Variables}
There are several files \TeX\ must look for when processing a document;
these include format files, font metric files, and auxillary input files.
Since people might choose to move these files from their default places,
or rename the volume on which they are stored, \TeX\ reads several
environment variables and uses them to search for these files.
An environment variable consists of two strings of characters: a name, and
some contents.  Included with the \AT\ package is a program \.{set} that
can be used to examine and change these environment variables.  Invoke this
program now by typing:
\cmd{1> set}
\noindent
The program should simply return with no output; this is because no
environment variables are set.  If you invoke the program with no arguments,
it displays all of the current environment variables.  Now, type
\cmd{1> set foo=bar\\
1> set\\
foo=bar\\
The first command set the environment variable \.{foo} to \.{bar}, and the
the second simply displayed the current variables.  Now, set \.{foo} to
\.{mung}:
\cmd{1> set foo=mung\\
1> set\\
foo=mung\\
\noindent
exactly as expected.  You can delete an environment variable by not following
it with an equals sign or a string:
\cmd{1> set foo\\
1> set\\
\noindent
\TeX\ examines the following environment variables.  If they are not set, it
uses the given default.
\cmd{texmacros=tex:macros\\
texfonts=tex:fonts\\
texinputs=.,tex:inputs\\
texformat=plain\\
texopts=}
\noindent
The first three are paths.  They are the devices or directories that contain
the appropriate files.  For instance, when \TeX\ needs to load a format file,
it searches the directory \.{tex:macros}.  When it is looking for a source
file, it searches the current directory first (the `\.{.}', borrowed from Unix)
and then the directory \.{tex:inputs}.  The fourth environment variable is the
\.{texformat} variable; this is used to set the default format file that \TeX\
loads in.  If you create your own format file called, for example,
\.{plane.fmt}, you can tell \TeX\ to load it rather than \.{plain.fmt}
by simply setting this variable to \.{plane}.  This is handy if you
use La\TeX\ rather than plain \TeX, since you can simply set this variable
to \.{lplain} and voila! \TeX\ becomes La\TeX.  The last environment
variable can be used to automatically run \TeX\ in the quick loop mode by
setting it to \.{R}.  This is recommended if you have sufficient memory.
If \TeX\ requests the Workbench disk when you think it should not, it
might be because \TeX\ is trying to determine the value of some environment
variables.  Environment variables on the Amiga are implemented as a library.
If no environment variables are set, the Amiga attempts to load the file
\.{libs:environment.library}, which is usually on the workbench disk.  To
prevent \TeX\ from requiring the Workbench disk, simply `set' some random
environment variable, and \TeX\ will be happy.  For instance, the command
\cmd{1> set foo=bar}
\noindent
should suffice.  This is also true of \.{preview} and all of the Amiga\TeX\
printer drivers.
%%   VII.  Using preview
\sec{Using Preview}
The preview program  allows you to display your \TeX\ output on the
Amiga monitor in a highly interactive fashion.  Its primary purpose
is to shorten the edit-\TeX-print cycle, to allow you to create
your documents more quickly and more conveniently.
As the preview program goes through its operations, its pointer
will change.  When preview is idle and waiting for a user action, the
pointer will appear a small arrow, similar to the workbench pointer.
When preview is redrawing a page, the pointer will appear to be a
pencil drawing a black line.  Finally, when preview needs to load a
font, the pointer will become
a large black lower-case `a'.  By watching the pointer, you can
follow the operations of the preview program.
If a font that the previewer needs is not found, the screen flashes
and an error message appears on the screen title bar.  In addition,
the font metric file for the font will be loaded, and the information
contained there used to create rectangular `characters' of the size
and shape of the actual font characters.  Thus, though these fonts
will certainly not be readable, they will give you some idea of
layout and style.
Note that at very low resolutions, like those required for preview,
some small characters might degenerate badly, or even disappear entirely.
The typewriter font is a particularly good example of this.
Unlike \TeX,
where the user input is strictly through the keyboard, the user
supplies input to the preview program mainly through the gadgets
and menus of the screen.  A few keys on the keyboard duplicate the
function of the gadgets for expert users.
%%         A.  Gadgets (screen)
\sub{Preview Gadgets}
%%             1.  Drag gadget
%%             2.  Hide screen/show screen
The preview program may be run either on a custom screen or the
workbench screen.  The default is a custom screen.  If it is running
on a custom screen, 
the top of the preview screen will contain the three default screen gadgets.
In the upper right corner will be the screen-to-front and screen-to-back
gadgets; the rest of the title bar will be the screen drag gadget.
%%             3.  Close gadget
Now we progress to the gadgets on the window title bar.  The close gadget
is a little square with a dot in the middle in the upper left corner.
Selecting this gadget will terminate the program, freeing all of its
memory.  Normally you would use only this gadget if you are through with
\TeX\ for the day, or if you have only 512K and want to run \TeX.
The previewer will peacefully coexist with other well-written Amiga programs.
Another way to exit the program is with the `Q' key on the keyboard.
%%             4.  File name gadget
%%             5.  Page number gadget
Next consider the file name gadget.  This gadget is the blank area in
the left portion of the window title bar.  When
have selected this gadget, a cursor will appear on the title bar; you
can now type the name of a file to preview (less the \.{.dvi} extension).
(If a file name is already in the gadget, you will need to clear it by
hitting the DEL key a few times.)
Hit carriage return, and the file will be opened.  If the file does not
exist, the screen will flash and an error message will appear on the
screen title bar.  Another way to select the file gadget is to simply
hit the `F' key on the keyboard; the current file name will be cleared
and the cursor will be positioned in the gadget ready for your file name.
The previewer buffers information about the current job in memory to
make redrawing the page faster.  If you make changes to the document and
rerun \TeX, this information is no longer valid and must be flushed.
To do this, simply select the file name gadget and hit carriage return.
All information about the file will be flushed, and the file will be
reopened as if you had started preview fresh.  Hitting
the `F' key and then carriage return has the same effect.  If you
use the tracking mode described later, this will not be necessary.
The page number gadget is the blank area next to the file name gadget.
As you scan around through the document, this gadget will
contain the current page number.  To go to a random page, simply hit
this gadget and type a new page number; if the page exists, it will
be displayed.  Again, the `P' key provides a convenient shorthand for
selection of this gadget.
The portions of the window title bar that are not gadgets are used
as a window drag gadget.  You can drag the window around on the screen
by selecting and dragging on the title bar.
\TeX\ allows more than one page to have the same number.  For instance,
if you turn page numbering off, all of the pages will be numbered zero.
Subsequent occurrences of the same page will be numbered, for instance,
0.1 for the second occurrence, 0.2 for the third, etc.  The first occurance
will always be numbered just 0.
%%             6.  Zoom/unzoom gadget
The next gadget, which has two small rectangles, one larger than the other,
is the zoom/unzoom gadget.  At any time the previewer is either in a zoom
state or an unzoom state; the zoom state usually displays the document at
a higher resolution than the unzoom state.  Selecting this gadget will
toggle between the zoom and unzoom states.  The default unzoom resolution
is 91 dots per inch; the default zoom resolution is 120 dots per inch.
Note that the units are screen pixels per document inch, not screen pixels
per screen inch, which is of course fixed.  The `S' key duplicates the
function of this gadget.
%%             7.  Back page gadget
%%             8.  Forward page gadget
The next two gadgets, which appear as arrows pointing to the left and
right, are the forward and back page gadgets.  Selecting the arrow
pointing left displays the page before the current one; selecting the
one pointing right displays the next page.  The left and right arrow
keys on the keyboard also provide this functionality.  In addition, the
space bar may be used to go to the next page, and the delete and backspace
keys go to the previous page.  These latter combinations (space and
backspace) also go to the top of the new page.
%%             9.  Scroll bar gadgets
The long, narrow gadgets on the left and bottom of the screen are the
scroll bar gadgets.  These gadgets are very similar to the scroll
bar gadgets in other Amiga applications, and it is worthwhile to get
familiar with their operation.  The scroll bar appears as a long, thin
rectangle inside a longer, slightly thicker rectangle.  The length of
the larger rectangle represents the size of the page in one dimension,
and the length of the shorter rectangle is proportional to the amount
of that page that is currently displayed on the screen.  Thus, if one
third of the vertical length of the document fits on the screen, then
the scroll bar body (the inner rectangle) will be one third of the length
of the scroll bar.  The position of the scroll bar body within the
scroll bar is also proportional to the position of the displayed text
on the entire page.
To move the scroll bars and thus the page, you need to select the scroll
bar body, and drag it in the direction you want the page to move.  If
you are currently looking at the middle third of the page and you wish
to see the top third, you must move the pointer to the vertical scroll
bar (on the right), select the body and hold the select button down,
and move the mouse up.  The scroll bar body will follow.  When the
position is correct, release the select button.  The page will then be
redrawn.
Alternatively, if you click the select button above or below the scroll
bar body, the body will move its length in the appropriate direction.
This is a quick way to get to the top of the page; simply move the
mouse to the top of the vertical scroll bar, and click several times.
The up and down arrow keys also move the page up and down on the screen.
If you hold the shift key down while you press the up and down arrow keys,
the page will move up or down one-half of the screen height.
In the lower-right hand corner is the resize gadget.  Select and drag
this gadget to resize the previewer window, either on the workbench screen
or a custom screen.
$$\vbox{\halign{\strut\vrule\quad\hfil #\hfil\quad\vrule\quad&#\hfil\quad\vrule\cr
\noalign{\hrule}
\multispan2{\vrule\hfil\strut Previewer Keyboard Commands \hfil\vrule}\cr
\noalign{\hrule}
(backspace)&Go to top of previous page\cr
(delete)&Go to top of previous page\cr
(space)&Go to top of next page\cr
$\leftarrow$&Go to previous page\cr
$\rightarrow$&Go to next page\cr
$\uparrow$&Move up one screen\cr
$\downarrow$&Move down one screen\cr
(shift)-$\uparrow$&Move up one half screen\cr
(shift)-$\downarrow$&Move down one half screen\cr
C&Close {\tt dvi} file\cr
F&Enter new file name\cr
P&Go to specified page\cr
Q&Exit previewer\cr
S&Toggle size selection\cr
\noalign{\hrule}
%%         B.  Menus
%%             1.  Project menu
\sub{Preview Menus}
There are seven main menus on the preview program.  The first is the
`project' menu, and it has five items on it.  The first item is `colors',
which allows you to change the foreground and background colors for
preview.  On a custom screen,
selecting this item brings up a colors requester with several
gadgets on it.  While the colors requester is on the screen, all other
input to the program is blocked; you must select the `use' (to retain
your color changes) or `cancel' (which restores the colors to their
previous state and exits)
gadgets to use the program further.  The `background' and `foreground'
gadgets select which color is currently being modified.  The `reset'
gadget sets the colors back to what they were when the requester first
appeared on the screen.  Finally, the three scroll-bar gadgets allow
you to change the intensities of red, green, and blue in the current
color.
On the workbench screen, the `colors' item brings up a submenu with
the twelve possible combinations of foreground and background colors
available on the workbench.  Select the one you prefer.
The second option is the `close file' option, which is used to close
the \.{.dvi} file so \TeX\ can be run again.  If this option is not
used before \TeX\ is rerun, it will complain that it can't open the
\.{.dvi} file because the previewer has it open for reading.  The
key `C' on the keyboard duplicates this menu selection.  Again, this
option is not necessary if you select one of the tracking modes.
The next option on the project menu is the `release memory' option.
As the previewer needs fonts to draw the pages on the screen, it loads
them off the disk.  When memory starts running low, preview starts to delete
the fonts it loaded on a least-recently-used basis.  However, preview
can easily use a lot of memory for font storage.  This second
option instructs the program to delete all of the fonts from its memory.
This is useful if you want to run another program and you suspect memory
is low.
The fourth option on the project menu is the `save configuration'
option.  This option saves the current state of the preview program,
including screen mode, zoom and unzoom values, window size and placement,
colors, page size and margins, and tracking mode.  The next
time the preview program is run, the settings of these values will
be read from this configuration file.
The last option on the project menu is the `quit' option; it behaves
exactly as if you had selected the close gadget on the window by exiting
the program.
%%             2.  Zoom/unzoom menus
The next two menus are the `zoom' and `unzoom' menus; these are used to
select the resolution for these two modes.  Either may take on values
between 58 and 189 dots per inch, and the `zoom' mode does not necessarily
have to have a higher resolution than the `unzoom' mode.  If the mode
corresponding to the menu you select is the currently active mode, the page
will be immediately redrawn at the new resolution; otherwise, the new
resolution will simply be stored for the next time you hit the zoom/unzoom
gadget.
In addition to the sizes from 58 to 189, there is a new `full' size option
which will attempt to display the entire page in the previewer window.
Normally, fonts at such a small resolution will not exist, so the page will
not be readable, but this mode should give you an idea of what the page
will look like.  If you resize the window, you must select this option
again to get the previewer to calculate a new size.
%%             3.  Borders menu
The fourth menu is the borders menu; the border consists of the lines that
represent
the edges of the paper on the screen.  By default, preview (and \TeX\ itself)
assumes that the size of the paper is 8 1/2 by 11, and that there are one inch
margins at the top and left.  The first option on this menu allows
you to toggle the borders on or off.  The second option allows you to `reset'
the borders back to the default values, in case they get changed.  The third
option sets the page size to `landscape', that is, 11 by 8 1/2, with one
inch margins.  (If the \.{.dvi} file contains a \TeX\ `special' command
consisting of the word `landscape', this is selected automatically.)
The fourth option of the `borders' menu allows you to change the
size and margins of the paper arbitrarily.  When you select the `set size'
option, a window will be opened on the workbench screen, and the current
size and margins displayed (in inches).  Simply enter new values, or hit
carriage return to keep the old values.  As you enter the values, they will
be checked for consistency; if any of the values you enter are unreasonable,
the program will prompt you for another value.  To exit quickly, simply hit
the carriage return key four times.
The fifth option of the borders menu allows you to display two facing pages
of the current \.{dvi} file at the same time.  This is usually most useful
when running in the full page magnification.  All of the remaining keys
retain their meanings, so selecting the right arrow gadget will move you
forward only one page; to move forward two pages, you simply select it
twice.  (You don't need to wait for the previewer to redraw the window
between selections.)
%%             4.  Modes menu
The fifth menu, `display', allows you to change the operating mode of the
preview.  There are currently three modes, each with advantages and
disadvantages.
The first and default mode is the interlace mode.  In this mode, the page
is drawn on a 640 by 400 pixel screen with interlace on.  This high
resolution allows fairly readable characters with a correct aspect ratio,
but the flicker caused by the interlacing might be annoying.  There is
a section following this one that describes how to deal with this flicker.
The second mode is the stretched mode.  Here, the page is drawn on a 640 by
200 pixel screen, using the same fonts as for the interlace mode.  The
characters are still well defined, but the aspect ratio is off by a factor
of two; hence the name.  The screen is rock steady in this mode.
The screen is also rock steady in the third mode, non-interlace, that is
also drawn on a 640 by 200 screen.
The aspect ratio is corrected by modifying the fonts as they
are loaded; this creates much cruder but generally acceptable characters.
Which of the three modes you use depends largely on which bothers you the
least; the interlace mode and flickering, a bad aspect ratio, or crude
characters.
The fourth selection on the `display' menu allows you to move the preview
window to the workbench screen, or back to a custom screen.  By default,
the previewer opens on a custom screen.  It runs faster on a custom
screen, and usually takes less memory as well.  In addition, you can
select any of the three modes on a custom screen.  Running on a workbench
screen allows you easier access to your other windows, however.  If you
run the previewer on your workbench screen, you will only be able to use
the interlace mode if your workbench is interlaced (this is selectable
in Preferences), and you will only be able to use the stretched mode and
the non-interlace mode if your workbench is not interlaced.
The sixth menu is the `tracking' menu.  This feature allows the previewer
to follow \AT\ in its processing of \TeX\ files, automatically displaying
the new file as \AT\ finishes processing the first page.  There are three
selectable modes.  The first is `independent', in which the previewer and
\AT\ are independent programs with no communication.  In this mode, you
must explicitly close and reopen the \.{dvi} file to redisplay it.
In the second mode, `track file', as \TeX\ finishes the first page in a
\.{dvi} file, it notifies the previewer.  The previewer then automatically
displays that new file.  You still maintain full control over the previewer,
and can preview any page that \AT\ has finished.  For instance, if you are
working on a thirty page report, and \AT\ has finished twenty pages, you
can preview any page from one through twenty.  This is the recommended
mode of operation.
The third mode, `track page', displays each page as \AT\ finishes it.
In this mode, you no longer control which pages are being previewed.
This mode is most useful in trying out small math equations or such,
typing them directly to the single splat prompt of \TeX\ and typing
\.{\ttbackslash vfill\ttbackslash eject} after each.
%%             5.  About menu
The last menu is the `about,' or `blurb,' menu.  It displays a copyright
notice and the version number of the software.  Please let us know what
this version number is when reporting bugs or missing features in the
preview program.
%%         C.  Coping with the interlace mode
\sub{Coping With Interlace}
When the Amiga uses a display mode with 400 dots vertically, it redraws
the screen thirty times a second rather than the normal sixty.  This
is called `interlace mode' because of the way the screen is redrawn.
To the human eye, the screen appears steady when redrawn at sixty
frames per second, but unfortunately, the human eye notices the
redrawing at the thirty frames per second.  In the interlace mode,
the screen appears to shake; this is called flicker.
The Amiga's flicker may be handled or reduced in several ways.
The first and best way is to buy a long-phosphor monitor.  These are
relatively expensive at the moment, but the price is dropping slowly.
(Commodore will release a long-phosphor monitor soon for approximately
\$500.)  On a good long-phosphor monitor, the flicker should be non-existent.
Another suggestion is to wear sunglasses while working in interlace mode.
Don't laugh until you have tried it.  Turning down both the room brightness
and the monitor brightness helps a great deal, as does selecting the
right combination of colors.  If none of these suggestions works for
you, the stretched and non-interlace modes eliminate the flicker altogether.
\sub{MoreRows}
For those with screens that are larger than 640 by 400, such as PAL
users or people familiar with the \.{morerows} program, the previewer
will work just fine, automatically.
%%         D.  Set options
\sub{Preview Environment Variables}
The preview program reads the settings of two environment variables:
\.{texfonts}, which is used in the same way as \TeX\ uses it, and
\.{texpacked}, which contains a list of the directories to search for
packed files.  The default value of \.{texpacked} is \.{tex:pk}.
\sub{Font Caching}
Supplied with \AT\ are approximately 1500 previewer fonts, occupying
six of the ten distribution floppies.  Typically, most of these
fonts will never be used by a typical user; yet, which fonts are
actually used varies widely.  To help handle this large number of
fonts, a font caching scheme has been implemented in the previewer.
Please note that with the release of February, 1988, a new caching
scheme has been implemented which is incompatible with the old one.
This coincides with the release of new, improved fonts as well.  So,
if this is an update for you, you should read this section carefully
and only use the new distribution.
The previewer will look for fonts in the places specified in the
\.{texpacked} environment variable.  If the required font is not
found in any of the specified directories, the previewer will
try to locate the font.  To help it locate the font, a file called
\.{tex:pk/fontvols} should exist.  (It is supplied on the \.{tex}
distribution floppy.)  This file might look something like this:
\cmd{cache 40 tex:pk\\
Red.Green=100d.69.76.83\\
Red.Yellow=100d.91.100.110\\
Red.Black=100d.120.131.144\\
Red.White=100d.144.158.173\\
Red.Purple=100d.189.207.227\\
Red.Red=100d.227.249.273.299.327.358}
\noindent
(Note that this file is just an example, and may not correspond to
the floppies actually distributed.)
The first line must start with the word `cache' or `nocache'.  If
the word is `cache', then font caching is enabled, and if a font
is found on one of the listed volumes, and there is room in the cache
directory, it is moved there.  Otherwise, the font is just loaded off
the distribution floppy to be used.  Next on the first line should
be an number which specifies how many blocks to leave free in the
cache directory.  If the number of free blocks falls below this
number, caching will be disabled.  It is usually nice to leave a few
blocks free, in case a program decides to write a configuration file
to the \.{tex} directory.  The third part of the first line is the
directory to use for caching.  Note that this must be a directory;
it cannot just be a logical name.  For instance, \.{ram:{}} is an
invalid cache directory.  Typically, \.{tex:pk} is used for the cache
directory.  It is recommended that you not change this until you have
tried using \.{tex:pk} and you are comfortable with the operation of
the caching.
The remaining lines contain the names and contents of the distribution
floppies.  If you buy a printer driver, it will have some more
font floppies which should be added to this list.  The names of the
floppies must be in a very specific format, to help the previewer
and other drivers know on which floppy to find a font.  For fonts
that have the same vertical and horizontal resolutions, as the previewer
fonts do, the line should be of the form
\cmd{{\it d\/}={\it n\/}{\it A}.{\it n}.{\it n}}
\noindent
for instance, where each {\it n\/} is replaced by a number, and the
{\it A\/} is replaced by a sequence of letters (typically just the single
letter `d'.)  In addition, the {\it d\/} is the actual name of the
floppy, which corresponds to the colors on the label.  The first
number specifies the dots per inch of the device
that the fonts on this floppy are intended for.  The remaining numbers
are important.  For each, there must be a directory on the floppy with
that number as a name, in which are a set of fonts at that resolution.
So, when the previewer cannot find a font in the default directories,
it searches the cache directory.  If the font is not there either, it
looks for a file in the subdirectory of the cache directory corresponding
to the appropriate resolution called {\tt pk.direct}.  This file has
information on which floppies contain exactly which fonts.  If this
file is not found, some of the font floppies are requested, and this
file is built.  Then, the previewer reads this file to find which floppy
that font is on, if it exists at all, requests that volume, and copies
the font into the cache directory.  If caching is turned off, the font is
not copied; it is just used directly off the floppy.
Thus, when the previewer or a printer driver first needs a font at a
certain resolution, the Amiga will request font floppies and spend some
time reading them.  Please be patient as it builds up the necessary
directory information; it should not take longer than a minute or so.
For this reason, if you rename some of the font floppies, add your own
fonts to the floppies or introduce a floppy of your own, you should type
the command
\cmd{1> delete tex:pk/\#?/pk.direct}
\noindent
to delete all of the directory files, so new ones can be automatically
constructed which reflect the new state of the floppies.
It is tempting, if you have a hard disk, to copy all of the font files
from the supplied font disks to your hard disk, so you don't ever need
to swap disks.  This is not necessary, and consumes a large amount of
disk space (about 4 megabytes.)  Nonetheless, if you must, the proper way
to do it is to type, for each font floppy supplied,
\cmd{1> copy Red.Green:\ TeX:pk}
\noindent
for instance, after you have set up your \.{TeX:{}} directory on your
hard disk.  You should then delete the \.{TeX:pk/fontvols} file to turn
caching off and to disable all reading from the distribution floppies.
\sub{Cleaning the \TeX\ Disk}
Between font caching, extra input files and large format files, the \.{TeX}
disk will sometimes fill up.  The first thing you can do to help prevent
this is to remove all of the files from the \.{TeX} disk you do not need.
You should remove \.{TeX:macros/tex.pool} unless you run
\.{initex} a lot.  You should probably only have one format file on your
\.{TeX} disk as well; if you use multiple format files, it is recommended
that you make multiple \.{TeX} disks, one for each format file.
Finally, you may choose to delete all of the files in \.{TeX:inputs} and
move them back only as you need them.
If the cache directory fills up, the previewer (or printer driver) will
print a warning, and turn caching off.  At this point, it is probably a
good idea to clean out your \.{TeX:pk} directory.
An easy way to clean the cache is to just remove all of
the fonts from the cache directory.  This can be done with the command
\cmd{1> delete tex:pk/\#?/\#?pk}
\noindent
(I'll bet you didn't know AmigaDOS was that smart.)  You should not use
the command
\cmd{1> delete tex:pk/\#? all}
\noindent
as this will also delete the file \.{tex:pk/fontvols} and the font directory
files, which you will then have to recreate.
It is somewhat
dangerous to use the ram disk as your font cache.  A number of Amiga
programs will crash if run on a machine with low memory, and \.{preview}
and the printer drivers can potentially move a lot of fonts into the cache
directory.  The previewer
will automatically cache fonts in ram during its normal run.  However,
if you really must use \.{ram:}, you can.  Because the ram device allocates its
blocks on demand, however, it will always appear full.  Thus, you should
set the number of reserved blocks (in the first line of \.{tex:pk/fontvols})
to a negative number, say, $-40$, to insure that the files are copied.
You should never use a negative value here when you are caching fonts to
a fixed size device, such as the ASDG recoverable ram disk, a hard disk,
or a floppy; doing so is guaranteed to crash the system at some point.
\sec{Printer Drivers}
``That's all very well and good,'' you might be saying to yourself at
the moment, ``but how do I get printed output?''  The standard Amiga\TeX\
package does not include the ability to output to any printer.  And
there is good reason for this.
Each printer requires its own set of fonts.  There is no easy way to
take a font at one resolution and scale it to another resolution; the
output of some Amiga word processors makes this evident.  Each printer
requires a specific set of fonts tailored for its resolution.  These
sets of fonts vary from three to seven full Amiga floppies; a
distribution of fonts and drivers for even a reasonable set of printers
would require on the order of fifty floppies!
For this reason, and several others, printer drivers must be available
separately.  These drivers are available for a price of \$100 apiece,
from the same people who distribute the Amiga\TeX\ package.
If you are looking for a printer to use with Amiga\TeX, please consider
a laser printer, preferably a PostScript printer.  The HP LaserJet Plus
is a good printer to consider.  The QMS KISS retails
for \$1900, but can be had for \$1700, and generates excellent quality
output.  PostScript machines start at around \$3500, but are possibly
the most versatile and usable printers available.  PostScript will
give you the greatest compatibility with both current software and
future software for anything requiring a printed page.
If you do not wish to spend the money for a laser printer, try
purchasing a 24-pin printhead printer, such as the Epson LQ series
or the NEC P6/P7 series.  These printers all deliver
superb print quality at a reasonable speed.  On the other hand, do not
expect the Okimate 20 (and some similar printers) to deliver reasonable
output quality; they simply do not have the resolution or clarity required.
Printer drivers are currently available for the QMS KISS, QMS SmartWriter,
HP LaserJet Plus,
and PostScript laser printers; the Epson LQ series, the Epson MX series
(including the JX, FX, EX, PX, RX, TX, etc.) and compatibles, the Citizen
150-D, the NEC P6/P7 series, and the ImageWriter II.
Other drivers are being developed on demand; if you have
a printer not on the list and not compatible with any on the list, call us.
If we cannot satisfy your printer driver requirements immediately, and
you have Manx C and are comfortable with the C programming language, we
can send you a package with which you can develop your own printer driver.
For dot-matrix printers, this typically takes a day or two and involves
at most a few pages of code (we supply the other 3500 lines.)  Laser
printers are typically more difficult, but we are pleased to help with
them as well.
%   Changing the size of TeX
\sec{Making \TeX\ Larger or Smaller}
Occasionally, \TeX\ will complain with a message like
\cmd{! TeX capacity exceeded, sorry [main memory size=18000].}
\noindent
(This particular message will only occur on a 512K Amiga.)  \AT\ allows
some limited control over internal array sizes with a file called
\.{tex:sizes}.   The variables you can modify are:
$$\vbox{\halign{#\hfil&&\quad\hfil#\hfil\cr
Variable&512K&Default&Maximum&Minimum&Size\cr
memmax&18000&65500&65500&5800&4\cr
memtop&18000&65500&65500&5800&(4)\cr
triesize (initex)&8000&8000&30000&7500&13\cr
triesize (tex)&6100&6100&6100&4\cr
poolsize&30000&50000&65500&27000&1\cr
maxstrings&2000&5000&30000&1780&2\cr
fontmemsize&6300&25000&65500&4900&4\cr}}$$
The 512K column contains the default values for a 512K machine, as
supplied in \.{texfiles:512/sizes}.  The default column indicates the
value used if no \.{tex:sizes} file is found.  The maximum values are
strict maximums; you cannot supply values greater than this without
dire consequences.  The minimum values are minimum to load plain \TeX.
The size column indicates how much memory each element takes.
Memmax should always be greater than or equal to memtop, and is usually
equal for maximum flexibility.  Ini\TeX\ ignores memmax, and uses the
memtop value instead.  The memtop size value is in parentheses because
it is just a position in a array of memsize elements.
The \.{tex:sizes} file must consist of just a list of seven numbers, in the
order given in the table above.  No error checking is performed, so you
must insure that you have created the file correctly and that you have
not exceeded the maximums listed above.
If you change \.{memtop}, you {\it must\/} create a new format file.
This is why a separate plain format file is supplied for the 512K version
of \AT.  This is because the format file is just a memory dump of \TeX's
internals, and some internal pointers depend on memtop.  A format file
created with an Ini\TeX\ which used a different \.{tex:sizes} file
than the current \TeX\ is the most common reason for the error message
\cmd{(Fatal format file error; I'm stymied)}
\noindent
All other values
can be changed with no change to the format file.  For instance, if you
are running out of font space, you could easily increase the fontmem value
to load more fonts.  (On a 512K machine, you cannot increase it much without
running out of room, however.)
%%   VIII.  LaTeX
\sec{La\TeX\ and Sli\TeX}
La\TeX\ and Sli\TeX\ are supplied with \AT\ on the third and fourth
distribution diskettes.  La\TeX\
is a macro package designed by Leslie Lamport that makes \TeX\ easier to
use by pre-packaging a number of document formats.  It is a large package,
however; it will not run on a 512K Amiga.  The rest of the documentation
describes La\TeX; Sli\TeX\ is but a variation of La\TeX.  To change the
instructions to those for Sli\TeX, simply change each occurance of
\.{lplain} to \.{splain}; no other changes are necessary.
%%          A.  Installation
To run La\TeX, there are several files you will need to move onto your
\.{TeX} floppy or hard disk.  The first of these is the La\TeX\ format
file, called \.{lplain.fmt}.  If you use La\TeX\ exclusively, you might
want to delete the \.{plain.fmt} file to make room for this file.
You will probably have to delete some \.{.pk} files off the \.{TeX}
floppy to make room if you are running from floppies.  I recommend
deleting the fonts starting from the higher resolutions, since these
fonts are used less often and take more space.
You will also need to move all of the style files (with the \.{.sty}
extension) from the La\TeX\ floppy into the \.{tex:inputs} directory.
This can be accomplished with the following command:
\cmd{1> copy latex:inputs/\#?.sty tex:inputs}
Again, you might have to delete some files to make room.  Alternatively,
to bring things up with a minimum of fuss, the following two environment
variable defines will allow you to run LaTeX by simply swapping floppies
as they are requested:
\cmd{1> set texinputs=latex:inputs,tex:inputs\\
1> set texmacros=latex:macros,tex:macros}
To tell \TeX\ to load the \.{lplain.fmt} file rather than the \.{plain.fmt}
file, you will need to execute the following set command:
\cmd{1> set texformat=lplain}
Alternatively, you can simply give \TeX\ the format file name followed by
an ampersand before the file name, as in
\cmd{\banner\\
**\&lplain foo}
\noindent
if \.{foo.tex} is the name of your La\TeX\ source.  This can be slower,
however, as the \.{plain.fmt} file is loaded into \TeX\ by default before
the double splat prompt is given.  If you give the ampersand on the
command line which invoked \TeX, the \.{plain.fmt} file will not be
loaded.  Using the environment variable mentioned above is the recommended
method for running La\TeX.
%%          B.  Necessity for multiple runs
\sec{Ini\TeX}
%%   IX.  IniTeX
The program \TeX\ has only about 312 control sequences built in.  These
control sequences are very primitive and thus quite difficult to use.
Therefore, before processing a document, \TeX\ loads in by default a
macro package called plain that contains approximately 596 more control
sequences built up from the primitives.
Parsing and processing the large amount of source in plain takes
a long time.  To eliminate this delay, the program Ini\TeX\ can
be used to create a `format file' that contains essentially a memory
image of \TeX\ after all of the macros have been loaded.  This
format file loads relatively quickly, since it needs only to be copied
into memory.
To illustrate the process of creating a new format file, we shall
assume that we want to create a preloaded \.{plain.fmt} file augmented
with the verbatim macros supplied in \.{tex:inputs/verb.tex}.
You will substitute your own macro package for \.{verb.tex}.
Before we get started, note that you cannot run Ini\TeX\ on an Amiga
with less than a megabyte of RAM.  If your Amiga does not have enough
memory, borrow a friend's.
To create your format file, you must make sure that you have at least
150K free on your working disk.
First, you must move the file containing your macros and the \.{tex.pool}
file to your current directory.  The following commands should do the
trick:
\cmd{1> copy tex:inputs/verb.tex verb.tex\\
1> copy tex:macros/tex.pool tex.pool}
Insert the disks as requested.  Now you have to tell \TeX\ to look on
the \.{TeXfiles} disk for some of its input files; specifically, the
\.{plain.tex} and \.{hyphen.tex} files.  This can be accomplished by:
\cmd{1> set texinputs=.,texfiles:inputs}
Now you can invoke IniTeX, and load the basic macros of plain:
\cmd{\advance\hsize by 1in %  So no overfull messages
1> texfiles:c/initex\\
\cbanner\\
This is CTeX, Amiga Version 2.9c (INITEX)\\
**plain\\
(texfiles:inputs/plain.tex Preloading the plain format:\ codes, registers,\\
parameters, fonts, more fonts, macros, math definitions, output routines,\\
hyphenation (texfiles:inputs/hyphen.tex))\\
The macros of plain have been loaded, so now you load your own:
\cmd{*\ttbackslash input verb\\
(verb.tex)\\
Once all of the macros you wish to include have been loaded, you can
create the actual format file by typing the command \.{\ttbackslash dump}
to the splat prompt.  Ini\TeX\ will create the format file and exit.
In this case, the format file will receive the name \.{plain.fmt}, since
that is the first file we specified.  If you replace the supplied
\.{plain.fmt} file (in \.{tex:macros} with this one, all of your
\TeX\ documents will have
access to your new macros automatically.  However, if you want to use
the regular plain package in addition to your augmented plain, you will
have to rename this format file, and copy it to \.{tex:macros}.  Then,
to use it, you will have to specify on the command line
\cmd{1> tex \&foo bar}
\noindent
if you renamed the format file \.{foo.fmt} and you want to process the
\TeX\ source in \.{bar.tex} with those macros.  Alternatively, you can
omit the \.{\&foo} part by executing the command:
\cmd{1> set texformat=foo}
\noindent
which will tell \TeX\ to use the \.{foo.fmt} file by default.
%%        A.  Required files
%%        C.  Making TeX larger or smaller
%   BibTeX
\sec{Bib\TeX}
Bib\TeX\ is a bibliography database system for use with La\TeX.
For basic documentation, please refer to the {\it La\TeX\ User's
Guide and Reference Manual.}  Bib\TeX\ is supplied on six files.
The first is \.{TeXfiles:c/bibtex}, which is the executable; if
you use Bib\TeX, you will probably want to move this into your
\.{c:{}} directory.  The remaining files are in \.{LaTeX:inputs},
with the extension \.{.bst};
these are the standard bibliography styles.  To use these,
move the files corresponding to the styles you will use into the
directory \.{TeX:inputs}.  That is all you need to do.
Bib\TeX\ uses two environment variables.  One is \.{texinputs}, which
is used just as in \TeX.  The other is \.{texbib}, and it tells Bib\TeX\
where to find your bibliography data base.  By default, this is set to
the same thing as \.{texinputs}.
\sec{AMS\TeX}
AMS\TeX\ is another macro package made available through the American
Mathematical Society.  Like La\TeX, it requires a megabyte or more of
memory to run.  It is supplied in source form only; if you wish
to use it, you will need to create a format file for it.  (See the section
on \.{initex} for details.)  To create such a format file, you will need
add \.{LaTeX:AMSTeX} to your \.{texinputs} path at least temporarily,
and then run \.{initex} over \.{aplain.tex}.  Remember to reset the
\.{texinputs} path to what it was originally afterwards.
%%   X.  Speeding up TeX using the ram disk
\sec{ARexx Support}
ARexx is a general purpose scripting and macro language for the Amiga.
It is functionally identical to REXX on IBM mainframes, but has many
additional features, allowing such uses as management of interprocess
communication.  Instead of making each application on the Amiga understand
every other application, the developer simply adds an ARexx port to his
application, and provides a certain set of primitives which other
applications can use.  As more and more programs become ARexx compatible,
you will be able to combine and use Amiga applications in incredible
ways.
With this section of the manual and some documentation from the editor
you intend to use, you should be able to construct a fairly nice integrated
environment for \TeX.  If you are not familiar with ARexx, I recommend that
you read the ARexx manual before embarking on this; this document takes
no pains to explain ARexx.
Please note that neither ARexx nor the \.{mg} editor used here are
supplied with the Amiga\TeX\ package.  ARexx is available from William
Hawes, Box 308, Maynard, MA~~01754.  One ARexx compatible editor,
TxED Plus, is available from MicroSmiths, Box 561, Cambridge, MA~~02140.
The \.{mg} editor illustrated here, complete with source, is available
from Tomas Rokicki, Box 2081, Stanford, CA~~94309; simply send a blank
disk and an SASE.  If you have ideas for more ARexx primitives to be
added to \TeX, the preview program, and drivers, please let me know!
\sub{\AT\ ARexx Primitives}
This section is the main reference portion of the ARexx port.
The rest is simply examples of ARexx scripts.
The Amiga\TeX\ Arexx port is called (surprisingly enough)
\.{AmigaTeX}.  It is strictly a server port; it never makes
requests of ARexx.  Amiga\TeX\ makes four primitives available
to ARexx.  These four primitives are:
{\vb\leftskip=30pt\parindent=-30pt
{\tt Abort}  This command aborts the current \TeX\ job, if one
exists, and goes back to the \.{**} prompt the quickest way
possible.  It returns 0 if it didn't need to do anything
(i.e., \TeX\ was waiting for another file) or 1 if it had to
interrupt \TeX.
{\tt Prompt} This command sets up \TeX's current prompt
into the cliplist in a variable by the name of \.{AmigaTeX.Prompt}.
If \TeX\ is working, then it makes this variable the null string.
If \TeX\ couldn't open a file and is waiting for a new name, it returns
the value `\.{file}'.  Otherwise, the prompt should be one of
`\.{**}', `\.{*}', `\.{? }', `\.{insert>}', or `\.{=}'.
{\tt ErrorLoc} This command sets the current error file name,
line number, and character position in the cliplist variable
\.{AmigaTeX.ErrorLoc}. This value has the form `file line char'.
If there is no error, then this string should be empty, but you
might check the prompt.
{\tt TeXify} {\it filename} This command sticks the rest of its command
line into the \.{**} prompt, and tells TeX to start.  Only valid at
the \.{**} prompt.  If any other prompt is displayed, it returns a 1
and does nothing.
Don't worry if this isn't all perfectly clear at the moment; a few
examples should illustrate it sufficiently.
\sub{Invoking \TeX\ on a Buffer}
We shall start by illustrating how you might invoke \TeX\ over a
buffer.  For an editor we will use a version of \.{mg}, an editor
similar to GnuEmacs, modified to add ARexx capabilities.  The
startup file (\.{s:.mg} in this case) of the editor might look
something like this:
\ttcmd{^X( ^X^S $x 'rexx' 'TeXify' ^X)\\
$x 'global-set-key-macro' \!f1\\
^X( $x 'rexx' 'ToError' ^X)\\
$x 'global-set-key-macro' \!f2}
The first line of this file defines a macro which saves the current
file, and then sends a message of \.{TeXify} to ARexx.  The second
line binds this macro to the first function key.  The third line
defines a macro which sends a \.{ToError} message to ARexx, and the
fourth line binds this to the second function key.  Your initialization
file for your editor will almost certainly be more readable.
In order to run the following macro, you should have loaded the
ARexx support library \.{rexxsupport.library}.  This can be loaded
with the command
\cmd{1> rx "say addlib('rexxsupport.library',0,-30,0)"}
\noindent
When ARexx gets the \.{TeXify} message, it first checks to see what
extension the application is telling it to use for the file name.
Our editor passes the extension \.{.mg}, so ARexx looks for the
file \.{rexx:TeXify.mg} and tries to load it as a ARexx script.
This file looks like:
\ttcmd{/*   This file texify's its argument */\\
options failat 5\\
filename = getclip('mg.BufferName')\\
if showlist('Ports','AmigaTeX')=0 then do\\
\t address command "newcli from s:StartTeX"\\
\t do i=1 to 10\\
\t\t if showlist('Ports','AmigaTeX') ~= 0 then leave i\\
\t\t address command 'c:Wait 5'    \\
\t end\\
\t if showlist('Ports','AmigaTeX')=0 then exit\\
end\\
address 'AmigaTeX'\\
do i=1 to 10\\
\t 'Abort'\\
\t if RC=0 then leave i\\
\t address command 'c:Wait 5'\\
end \\
'TeXify' filename\\
exit}
\noindent
The \.{failat} option is necessary so that the error returns from
Amiga\TeX\ don't make the script abort.  (If Amiga\TeX\ gets a
command it doesn't understand, it returns error code 10, which will
still make the script fail.)  The first thing the script does is get
the file name from the editor.  Whenever \.{mg} invokes an ARexx macro,
it stuffs the file name of the current buffer into the cliplist.
Then our macro sees
if it can find an existing \TeX\ port.  If it cannot, then it runs
\TeX\ by getting a new CLI and reading its input from the file
\.{s:StartTeX}, which looks like:
\ttcmd{cd vd0:\\
\noindent
Note the \.{cd} command; this is necessary because by default, the
new CLI has as its current directory \.{df0:{}}, and we do all of
our work from the \.{vd0:{}} recoverable ram disk.  We then iterate
a few times, waiting for \TeX\ to come up, and if it doesn't come
up after approximately a minute, we bail out.
Finally, once we have an Amiga\TeX\ port, we set the default host
environment to it.  Then, we send the Amiga\TeX\ \.{Abort} command
until the return code of 0 indicates success.  After this, we send
the \.{TeXify} command to Amiga\TeX, and return.
\sub{Finding An Error}
If Amiga\TeX\ finds an error, then it stops with a `\.{? }' prompt,
and waits for user interaction.  Within the editor, it is possible
to go to the location of the error with a single keystroke.  This is
our second illustrative ARexx macro, called \.{rexx:ToError.mg}.
\ttcmd{/*  Now we try to determine the error location */\\
options failat 5\\
address 'AmigaTeX' 'ErrorLoc'\\
errorloc = getclip('AmigaTeX.ErrorLoc')\\
if errorloc = "" then exit\\
else parse var errorloc filename linenum charpos\\
address 'mg' "^X^F '"||filename||"'"\\
address 'mg' "$x 'goto-line' '"||linenum||"'"\\
address 'mg' "^U "||charpos-1||" ^F"\\
exit}
\noindent
This script is shorter and even easier to explain.  Again, we need
the \.{failat} option.  After setting that, we send Amiga\TeX\ an
\.{ErrorLoc} call.  This places into the ClipList the location
of the error.  We pull this from the cliplist, and exit if it is
null.  If it isn't, we parse it into a filename, line number, and
character position.  Then we send the editor commands to visit that
file (if it already isn't), and to go to the correct line and character
position.
\sec{Using the RAM disk}
Judicious use of the RAM disk or one of the available recoverable
RAM disks can speed up \TeX\ processing on the Amiga
significantly.  You will probably only be able to take advantage
of some of the tricks illustrated in this section if you have at least
one megabyte of RAM.
\sub{Moving the Format File to RAM}
To reduce the delay involved in loading the format file each time \TeX\ is
run, you might want to copy it into RAM.  This will require approximately
111K of RAM for plain and 260K for La\TeX.  A typical sequence of operations
to perform this might be
\cmd{1> makedir ram:macros\\
1> copy tex:macros/plain.fmt ram:macros\\
1> set texmacros=ram:macros,tex:macros}
\noindent
With the new \.{-R} option to \AT, this is no longer the best way to get
this effect.
\sub{Moving Your Working Directory to RAM}
Another possibility is to move your working directory to the RAM disk.
This will reduce disk traffic dramatically.  The only potential problem is
that if the machine crashes or loses power, all of your files in the RAM
disk will be destroyed.  Therefore, you always want to edit your source
file off the floppy, and only create the \.{.dvi} and \.{.log} files on
the RAM disk.  To do this, before you invoke \TeX\ or the previewer,
\cmd{1> makedir ram:tex\\
1> cd ram:tex}
\noindent
The \.{makedir} command need only be executed once, but the \.{cd} command
should be executed from both the preview and the \TeX\ window.  Let us
say that your normal working directory is \.{df0:mysource}.  You should
also execute the following command before entering \TeX, so it knows where
to look for your input files:
\cmd{1> set texinputs=df0:mysource,.,tex:inputs}
\noindent
Now \TeX\ will look first on your working directory on the floppy, then
on the current RAM directory, and finally in the \.{tex:inputs} directory.
The editor should be invoked with \.{df0:mysource} as the current working
directory so files will be read and written to the floppy rather than
the volatile RAM disk.
\sub{Moving Everything to RAM}
If you have a lot of extra memory, you might consider moving all of
the \TeX\ files to RAM disk.  You can move all of the files on the standard
distribution disk and set things up to work entirely off RAM disk with the
following sequence of commands:
\cmd{1> makedir ram:tex\\
1> copy tex:\ ram:tex all}
\noindent
Now go out and get a cup of coffee; this will take a while.  When it is
complete, remove the \.{TeX} floppy and type
\cmd{1> assign tex:\ ram:tex}
\noindent
and follow the instructions in the previous section to move your working
directory to RAM.
%   Using foreign fonts
\sec{Importing Font Files}
Amiga\TeX\ is fully compatible with all versions of \TeX.  (An
implementation cannot be called \TeX\ unless it is fully compatible
with the standard.)  This allows you to import font files you have
created on a mainframe with METAFONT, for instance.  The \.{.tfm}
file must be moved into the \.{tex:fonts} directory, and any \.{.pk}
files must be moved into the appropriate subdirectory of \.{tex:pk}.
Since METAFONT creates \.{.gf} files, a program to convert these files
to \.{.pk} files is included.  It is called \.{gftopk}; to run it,
put the \.{.gf} file in your current directory, and invoke \.{gftopk}
with the name of the \.{.gf} file.  The conversion will be performed.
Likewise, if you have some old \.{.pxl} font files, you can convert
those to \.{.pk} files with the program \.{pxtopk}; it is invoked in
the same way as \.{gftopk}.
To use your local fonts with the previewer, you must create them at
a magnification of 100 dots per inch, multiplied or divided by some
power of $1.2^{1/2}$.  Thus, for a full set of previewer fonts, you
must create font files at resolutions of 69.44, 76.07, 83.33, 91.29,
100, 109.54, 120, 131.45, 144, 157.74, 172.8, for instance.  Actually,
you can select the resolutions you use most often and just create them.
When you download any font files, whether \.{.tfm}, \.{.pk}, \.{.gf},
\.{.pxl}, or whatever, you must be careful to download them as binary
files.  Refer to the documentation for the software you use to download
files for details.
You should then create a floppy containing all of your new fonts,
in the appropriate subdirectories.  For instance, a font called \.{script}
created at 131 dots per inch on a font floppy you named \.{myfonts:{}}
should be stored as \.{myfonts:131/script.131pk}.  You should copy the
\.{tfm} files to \.{TeX:fonts}.  Then, you need to add a line to the
\.{TeX:pk/fontvols} file such as
\cmd{myfonts=100dpi.69.76.83.91.100.110.120.131.144.158.173.207}
\noindent
if you have fonts at all of those sizes.  Finally, you should type
\cmd{1> delete tex:pk/\#?/pk.direct}
\noindent
to delete all of the directory files, so they can be recreated with
information about your new fonts.  Your fonts will then be automatically
cached in.
%   History of AmigaTeX; its origins and development
\sec{History}
\AT\ is a \TeX\ which functions exactly like the \TeX s on any
other machine, from DEC-2060s to IBM-PCs.  There is no difference;
a \TeX\ source file developed on one machine is fully compatible
with the \TeX s on any other machine.  How was the huge \TeX\
program, whose user manual is almost 500 pages long, crammed into
a 512K Amiga?
This section describes the history of \AT; how it was developed
and ported to the Amiga.  It assumes that the reader is conversant
about programming languages, \TeX, and some computer operating
systems.
\AT, as all current implementations of \TeX, started life as the
original source file of \TeX.  \TeX\ was written by Donald Knuth in
\.{WEB}, a system of structured programming and documentation.
\.{WEB} is mostly a macro preprocessor for both \TeX\ and Pascal,
allowing one to program in Pascal and document in \TeX, and providing
publication quality program documentation.  The program \.{tangle}
takes a \.{.web} file and converts it into a \.{.pas} Pascal source
file.
Unfortunately for those running Unix, few good Pascal compilers exist
for Unix, and those that do are typically very expensive.  Most Unix
sites running \TeX, therefore, were paying a significant performance
penalty.  Most Unix systems have good C compilers, though, so Tomas
Rokicki and $n^2$ Computer Consultants decided to translate \TeX\ into
C.  This translation was done automatically using the compiler tools
available under Unix, and it was not long before C\TeX\ came into
existence.  This version of \TeX\ has been ported to almost everything
running any brand of Unix, and almost invariably shows a marked speed
improvement over the Pascal version.
When Tom Rokicki got his Amiga, it was natural that he wanted to run
\TeX\ on it.  So he ordered a beta copy of the Manx C Compiler and
moved all of the source files for C\TeX\ onto floppies.  (At that time,
and even as this is being written, no good Pascal compilers exist for
the Amiga.)  Then he set to work.
There were bugs in the compiler.  These had to be gotten around.
Certain modifications had to be made to the source to make it work under
the Amiga operating system.  But finally, everything worked.  Even
then, hundreds of hours were invested in optimizing and rewriting major
sections of code in 68000 assembly language to make the final program
small and fast.
And then the real work started---writing the preview program.  This
program was coded completely from scratch.  It had to manage the dozens
and dozens of fonts that might be used, interpret \.{.dvi} files and
\.{.pk} files, handle user interaction through gadgets and menus, and
be fast.  It was a significant effort, but things finally fell into
place.  And that is the story of \AT.
\sec{Software Support}
%%   XII.  Support
%%        A.  Updates
Updates and revisions will be made available at a cost of \$10 per floppy
required for the update.  Notification of updates will be sent to all
licensed owners of \AT.
%%        B.  Bug reports
If you suspect you have found a bug in \AT, please mail a complete
description of the error, including any commands and source files
necessary to duplicate it, to us.  Include your telephone number and
when you can be reached, and we will get back to you as soon as possible.
%%        C.  Software support
If you have any questions about the operation of this program, please
re-read the manual carefully.  Then, reboot and start again.
If you have trouble,
we'll be happy to help answer any questions you might have.  Our
address is
\leftline{\hskip2\parindent\vbox{\hbox{\AT}
\hbox{$n^2$ Computer Consultants}
\hbox{Box 2736}
\hbox{College Station, TX~~77841}}}
Bug fixes will get faster response if you send them to
\leftline{\hskip2\parindent\vbox{\hbox{\AT}
\hbox{Radical Eye Software}
\hbox{Box 2081}
\hbox{Stanford, CA~~94309}}}
Tomas Rokicki, the author of the program, is available to answer
questions.  Simply leave a message on the answering machine at
(415) 326-5312, and he will get back to you as soon as possible.
%%        D.  Getting TeX on another system
\TeX\ has been ported to dozens of computer systems, and currently runs
on everything from the IBM-PC to the CRAY.  For microcomputer versions
of \TeX, check out the advertisements in {\it BYTE\/} and other
microcomputer magazines.  For mainframe distributions, contact Maria
Code at (408) 735-8006; she handles the distribution of \TeX\ tapes.
Note that she is not familiar with \TeX, she only distributes the tapes,
so please do not ask her technical questions.  The cost for the tapes
is nominal.
%%        E.  Joining TUG
The \TeX\ Users Group (TUG) is an organization dedicated to the
exchange of information about \TeX\ and its implementations.
General meetings are held once a year, and short courses at several
levels of `\TeX pertise' are given at several sites during the year.
Tapes of these courses are available for rental.  Site coordinators
for implementations of \TeX\ on particular machines help those with
similar configurations, and the {\it TUGboat}, featuring articles on
\TeX, is published at least semiannually.  Information is available
\leftline{\hskip2\parindent\vbox{\hbox{\TeX\ Users Group}
\hbox{c/o American Mathematical Society}
\hbox{P.~O.~Box 6248}
\hbox{Providence, RI~~02940}}}
\sec{Distribution File List}
%%   XIII.  Distribution disk and file list, and explanation
This is a list of all of the files on the ten distribution diskettes,
and a brief explanation of their purpose.  (This list may not be complete
because of last minute changes to the distribution.)
{\def\start{\vb\begingroup\parindent=0pt\tt\obeyspaces\obeylines}
\def\trats{\vb\endgroup}
\start
\ TeX: (disk 1 of 10)
\trats
These are all the font metric files that contain resolution
independent information about each font.  They include the
standard 102 \TeX\ fonts, with a couple extras thrown in to keep certain
macro packages happy.
\start
\     fonts (dir)
\       circle10.tfm                     circlew10.tfm
\       cmb10.tfm                        cmbsy10.tfm
\       cmbx10.tfm                       cmbx12.tfm
\       cmbx5.tfm                        cmbx6.tfm
\       cmbx7.tfm                        cmbx8.tfm
\       cmbx9.tfm                        cmbxsl10.tfm
\       cmbxti10.tfm                     cmcsc10.tfm
\       cmdunh10.tfm                     cmex10.tfm
\       cmff10.tfm                       cmfi10.tfm
\       cmfib8.tfm                       cminch.tfm
\       cmitt10.tfm                      cmman.tfm
\       cmmi10.tfm                       cmmi12.tfm
\       cmmi5.tfm                        cmmi6.tfm
\       cmmi7.tfm                        cmmi8.tfm
\       cmmi9.tfm                        cmmib10.tfm
\       cmr10.tfm                        cmr12.tfm
\       cmr17.tfm                        cmr5.tfm
\       cmr6.tfm                         cmr7.tfm
\       cmr8.tfm                         cmr9.tfm
\       cmsa10.tfm                       cmsl10.tfm
\       cmsl12.tfm                       cmsl8.tfm
\       cmsl9.tfm                        cmsltt10.tfm
\       cmss10.tfm                       cmss12.tfm
\       cmss17.tfm                       cmss8.tfm
\       cmss9.tfm                        cmssbx10.tfm
\       cmssdc10.tfm                     cmssi10.tfm
\       cmssi12.tfm                      cmssi17.tfm
\       cmssi8.tfm                       cmssi9.tfm
\       cmssq8.tfm                       cmssqi8.tfm
\       cmsy10.tfm                       cmsy5.tfm
\       cmsy6.tfm                        cmsy7.tfm
\       cmsy8.tfm                        cmsy9.tfm
\       cmtcsc10.tfm                     cmtex10.tfm
\       cmtex8.tfm                       cmtex9.tfm
\       cmti10.tfm                       cmti12.tfm
\       cmti7.tfm                        cmti8.tfm
\       cmti9.tfm                        cmtt10.tfm
\       cmtt12.tfm                       cmtt8.tfm
\       cmtt9.tfm                        cmu10.tfm
\       cmvtt10.tfm                      dummy.tfm
\       icmex10.tfm                      icmmi8.tfm
\       icmsy8.tfm                       icmtt8.tfm
\       ilasy8.tfm                       ilcmss8.tfm
\       ilcmssb8.tfm                     ilcmssi8.tfm
\       lasy10.tfm                       lasy5.tfm
\       lasy6.tfm                        lasy7.tfm
\       lasy8.tfm                        lasy9.tfm
\       lasyb10.tfm                      lcmss8.tfm
\       lcmssb8.tfm                      lcmssi8.tfm
\       line10.tfm                       linew10.tfm
\       logo10.tfm                       logo8.tfm
\       logo9.tfm                        logobf10.tfm
\       logosl10.tfm                     manfnt.tfm
\       trip.tfm                         
\trats
The \.{nul.tex} file is used to get out of \TeX's `could not open
file, type another file name' loop.
The \.{verb.tex} file has a set of macros for verbatim mode; the
\.{testfont.tex} file allows you to sample particular fonts.
The \.{plain.fmt} file is the
default plain \TeX\ format file for a machine with more than 512K.
The \.{tex.pool} file has all of \TeX's strings for Ini\TeX; you should
probably delete this file from your working \.{TeX} disk.
\start
\     inputs (dir)
\       nl.tex                           nul.tex
\       null.tex                         testfont.tex
\       verb.tex                         
\     macros (dir)
\       plain.fmt                        tex.pool
\trats
The \.{pk} directory contains the cache for all of the packed files.
Supplied on the \.{TeX} disk are a few sample fonts; the rest will be
loaded on demand from the font distribution disks.  The file
\.{TeX:pk/fontvols} contains a list of the distribution fonts and a
few other caching parameters.
\start
\     pk (dir)
\       fontvols                         
\trats
The openwindows command file is a typical way to open three windows in
which to run \TeX, the preview program, and an editor.  The samples
directory contains a very short, very simple \TeX\ example---the
default \.{story.tex} from the \TeX book.
\start
\     s (dir)
\       openwindows                      to-512
\     samples (dir)
\       story.tex                        
\trats
The second disk contains the executables, all of the special files
necessary on a 512K system, and the files necessary to recreate a
\.{plain.fmt} file.  It also contains this manual.  Execute the
\.{to-512} command file to install \TeX\ on a 512K system.  It also
contains a few sample files for \TeX.
\start
\ TeXfiles: (disk 2 of 10)
\     512 (dir)
\       plain.fmt                        sizes
\     c (dir)
\       bibtex                           gftopk
\       initex                           pktype
\       preview                          pxtopk
\       set                              tex
\       unamiga
\     inputs (dir)
\       hyphen.tex                       plain.tex
\     manual (dir)
\       amigatex.tex                     fontlist.tex
\     samples (dir)
\       heart.tex                        primes.tex
\       story.tex
\trats
The third floppy contains everything necessary to run
La\TeX, Sli\TeX, and AMS\TeX.  The first group is
the distribution of AMS\TeX\ (sources only).  To run
AMS\TeX, you must create an \.{aplain} format file.  If you do not
plan to use AMS\TeX, it is highly recommended that you delete these
files.
\start
\ LaTeX: (disk 3 of 10)
\     AMSTeX (dir)
\       amsppt.mor                       amsppt.sty
\       amstex.tex                       aplain.tex
\trats
To run La\TeX, all of the files in
the \.{inputs} directory should be accessible, and the \.{lplain.fmt}
file from the \.{macros} directory should be loadable by \TeX.  Sli\TeX\
is similar, but requiring the \.{splain.fmt} file.
\start
\     inputs (dir)
\       abbrv.bst                        alpha.bst
\       art10.sty                        art11.sty
\       art12.sty                        article.sty
\       bezier.sty                       bk10.sty
\       bk11.sty                         bk12.sty
\       book.sty                         fleqn.sty
\       ieeetr.bst                       ifthen.sty
\       leqno.sty                        letter.sty
\       makeidx.sty                      openbib.sty
\       plain.bst                        proc.sty
\       rep10.sty                        rep11.sty
\       rep12.sty                        report.sty
\       showidx.sty                      slides.sty
\       suthesis.sty                     titlepage.sty
\       twocolumn.sty                    unsrt.bst
\     macros (dir)
\       lplain.fmt                       splain.fmt
\trats
The fourth disk contains the files necessary to create new style
files and recreate the \.{lplain} and \.{splain} format files, and
some La\TeX\ samples.
\start
\ LaTeXfiles: (disk 4 of 10)
\     format (dir)
\       latex.tex                        lfonts.tex
\       lplain.tex                       sfonts.tex
\       slitex.tex                       splain.tex
\     samples (dir)
\       addendum.tex                     lablst.tex
\       local.tex                        sample.tex
\       small.tex                        testpage.tex
\     docs (dir)
\       art10.doc                        art11.doc
\       art12.doc                        article.doc
\       bezier.doc                       bk10.doc
\       bk11.doc                         bk12.doc
\       book.doc                         fleqn.doc
\       ifthen.doc                       leqno.doc
\       letter.doc                       makeidx.doc
\       openbib.doc                      proc.doc
\       rep10.doc                        rep11.doc
\       rep12.doc                        report.doc
\       showidx.doc                      slides.doc
\       suthesis.doc                     titlepage.doc
\       twocolumn.doc                    
\trats
The remaining six floppies contain fonts.  Each floppy contains two
or more sets of fonts of one size.  The names of the floppies correspond
to the colors of the labels, for easy location during font caching.
Thus, a floppy named \.{Red.Green} might contain fonts at size
100 and 110 dots per inch, such as \.{Red.Green:100/cmr10.100pk} and
\.{Red.Green:110/cmr10.110pk}.  In the file \.{TeX:pk/fontvols}, this
floppy might be identified with a line such as
\cmd{Red.Green=100d.100.110}.}
\sec{Changes From 1.3 Release}
Thank you for purchasing the update to the \AT\ package.  I think you will
be pleased with the changes that have been made to the package in the last
few months.
The current distribution includes the latest La\TeX, Sli\TeX,
and AMS\TeX, as well
as the latest \.{plain.tex} and other files.  In addition, a number of
minor bugs were found and corrected in the standard Stanford \TeX; these
bugs were also corrected in \AT, so this release corresponds fully with
all other \TeX\ implementations up to version 2.9.
The fonts have all been regenerated and improved as well, and a larger
set of fonts is distributed with this release; over 1500 fonts for the
previewer, and 770 fonts with each printer driver.  This is the full
standard set of \TeX\ fonts, including those for La\TeX\ and Sli\TeX.
Another useful improvement is the communication between \AT\ and the previewer.
If the previewer is running when \TeX\ attempts to open a \.{dvi} file, and
one of the previewer tracking modes is selected, the previewer will be
notified of the new file, and this file automatically displayed.  Thus, the
commands needed in the edit-\TeX-preview cycle have been reduced.  You no
longer need to close the file in the previewer, re-\TeX\ it, and reopen
the file in the previewer; you simply re-\TeX\ it and the previewer knows
about it.  This is covered in the description of the `tracking' menu
of the previewer.
A bug in the preview and printer drivers has been squashed; this bug
showed up if \.{TeX:pk/fontvols} did not terminate with a carriage
return, and sent the above programs into an infinite loop.  Many
small and large improvements have been made to all of the printer drivers.
Some other changes to \TeX\ have been made as well.
User input typed to a double asterisk prompt is saved for the next such
prompt.  Thus, you no longer have to retype
the file name to \TeX\ on subsequent times; simply hit carriage return.
The quick loop mode has also been added for extremely quick format file
loading; this is the \.{-R} option to \AT.  Four levels of user interrupt
have been added; {\it CNTRL}-F will always exit the program.  Some minor bugs
have also been found and swatted.  Support for the Amiga special characters
has been added.  Note that with the current version of
\AT, you can no longer exit the program with {\it CNTRL}-$\backslash$ unless
you are running \.{conman}.
A major bug has been found and fixed in \.{bibtex}, concerning use of
negative arguments to the \.{substring} operator.
The previewer has undergone the most dramatic changes.  These changes include
cosmetic changes so that it resembles other Workbench windows more closely and
some very minor bug fixes.  Menus now stay on even while the page is being
redrawn.  If the window is on the workbench screen, you can now select the
foreground and background color.  You can now see the entire page on the
screen at once, although you probably won't be able to read it.  The space
and backspace now go to the top of the new page instead of retaining the
old position.  The ability to view facing pages was added.  Environment
variables are now reexamined each time a \.{dvi} file is opened, so you can
change the font paths and have it take effect without exiting and reentering
the previewer.  System requesters now come up on the previewer's custom
screen, if one is in use.  The up and down arrow keys, when combined with
the shift key, move the page up or down one half of a screen, for those cases
when only half a paragraph is on the screen.
The font caching scheme has been changed incompatibally.  This means that
you should not use any of your old executables, and you should update the
\.{TeX:pk/fontvols} file according to the instructions in this new manual.
The changes were introduced to allow color-keying of the font disks, to
allow use of resolutions with more fonts than would fit on a single disk,
to allow the use of incomplete resolutions (such as magstep 9, at which
resolution only the Sli\TeX\ fonts are supplied) and to pack the distribution
font disks more tightly.  If you are using a printer driver, you must also
update the printer driver.
%%   XIV.  Glossary
\sec{Glossary}
This section contains the definitions of some of the more obscure
terms used in this manual.
{\leftskip=\parindent\parindent=-\parindent
\def\d#1:{\par{\bf #1}}
%%         boot
\d boot:
To start or restart the Amiga by pressing down the {\it CNTRL\/} key
and both Amiga keys (the fancy `A's on either side of the space bar).
Used as either a verb or a noun; comes perhaps inappropriately from
the phrase `lifting one by one's bootstraps'.
%%         CLI
\d CLI:
Command Language Interpreter; a program that takes the user's input
and parses it into commands and arguments, loads the commands and
executes it.  This is the traditional mode of operation of a computer,
in contrast with the desktop metaphor.
%%         desktop metaphor
\d desktop metaphor:
A method of user interface where files are represented as icons,
programs as windows, and the user `executes' commands by selecting,
dragging, and pointing with the mouse.  For instance, to delete a
file using the desktop metaphor, you would click on the icon you
want to delete, and drag the icon over to the trashcan, where you
would let go of the select button.
%%         double click
\d double click:
Two rapid presses of the select button; this is the way an icon is
activated in the Amiga.  If the icon represents a program, the
program is run; if the icon represents a directory, the directory
is opened and a window showing the contents of the directory is
displayed.
%%         driver
\d driver:
A program that takes a \TeX\ device-independent (or \.{.dvi})
file and interprets it, loading the rasters for the fonts as necessary,
and sends the required commands to a particular printer or other output
device to produce the document described.
%%         dvi file
\d{\tt .dvi} file:
A device-independent file is the output of the \TeX\ program; it
contains a description of the typeset document in a compact form
that is resolution and output device independent.
%%         environment variables
\d environment variables:
Global variables that the user can set and which are accessible to
programs in the machine.  An environment variable can be used to set
some option or convey some information to a program; for instance, they
might be used to tell \TeX\ where to find font files in a user-configured
system.
%%         fmt file
\d{\tt .fmt} file:
A format file is a compact form of a set of \TeX\ macros that is loaded
in every time \TeX\ is run to make those macros available.  The \.{fmt}
file is created by ini\TeX\ and consists of essentially a memory image of
\TeX\ after the macros have been loaded.  The default \.{fmt} file is
called plain \TeX; La\TeX\ uses another format file called \.{lplain.fmt}.
The format files must reside in the \.{tex:macros} directory.
%%         font
\d font:
A collection of printing characters of one style or size; for
instance, \.{cmr10} is Computer Modern Roman at 10 points.  The word font
is used to refer to both a particular style, independent of size, and
a particular style at each individual size.  \AT\ is currently supplied
with the standard \TeX\ 91 fonts; many different sizes of these fonts are
distributed for the previewer.
%%         gadget
\d gadget:
Some graphics imagery that, when selected with the mouse, starts some
operation.  For instance, the window-to-front gadget is in the upper
right hand corner of a window, and when you select it, it brings that
window in front of any other windows that might overlap it.
%%         icon
\d icon:
Some graphics imagery that represents a file, program, device, or
directory.  These can be activated or opened by double-clicking on
them with the mouse.
%%         info file
\d{\tt .info} file:
A small file containing the graphics imagery of the icon; associated
with an executable, directory, or data file.  When the executable,
directory, or data file is copied, renamed, or deleted, this file should
also be copied, renamed, or deleted, to keep the desktop metaphor
consistent.
%%         IniTeX
\d ini\TeX:
The ini\TeX\ program is a larger version of \TeX\ that takes more
memory to run; its purpose is to create format files from a set of
macros.
%%         interlace
\d interlace:
The process of refreshing a video screen at half the normal rate by
drawing alternate lines in each scan.  The Amiga uses interlace for
the screen modes that use 400 lines vertically; with a normal monitor,
interlace can cause flicker that can be annoying.
%%         Intuition
\d Intuition:
The set of routines in the Amiga that controls the user interface,
including the windowing, gadget, and menu routines.  A properly written
program on the Amiga will follow certain guidelines established by
Intuition to allow the simultaneous and convenient use of many several
different programs in the Amiga operating environment.
%%         kerning
\d kerning:
The addition or removal of spaces between characters due to their shape.
For instance, in the word `AVAILABLE', the `A' and `V' are moved closer
together; compare this with `A{}V{}A{}I{}L{}A{}B{}L{}E', with the kerning
turned off.  \TeX\ handles kerning automatically.
%%         LaTeX
\d La\TeX:
A macro package intended to both make \TeX\ easier to use and more powerful,
La\TeX\ was written by Leslie Lamport.  It is supplied with \AT, but requires
more than 512K to run.
%%         ligatures
\d ligature:
A ligature is the combination of two or more characters into one character.
For instance, the
`f' and `i' in `file' is a ligature; compare this with `f{}i{}l{}e', using
separate characters instead.  \TeX\ handles ligatures automatically; no
special characters need be typed.
%%         log file
\d{\tt .log} file:
A file that contains all of the terminal output during a run of \TeX; it
is created automatically along with the device-independent file for later
perusal of any errors.  It serves no purpose other than user enlightenment,
so it can be safely deleted at any time.
%%         loop mode
\d loop mode:
When \TeX\ is run on the Amiga in loop mode, the program does not exit
after finishing a job.  Rather, it restarts, and waits for another file
name.  This is to eliminate the delay in loading the \TeX\ executable
off the disk.  \TeX\ runs in the loop mode when it is invoked with no
file name, or when it is given the \.{-r} option before the file name.
%%         menu button
\d menu button:
The right mouse button.  This is called a menu button because pressing
it displays the menus for the currently active window on the screen
title bar.  To select a particular menu item, you hold the menu button
down, move the mouse to the menu name and then to one of the items
that will appear, and then release the menu button.
%%         pk file
\d{\tt .pk} file:
A packed file contains raster information for a particular font at a
particular resolution in a compressed format.  \TeX\ does not use these
files at all, but the preview program and any other drivers require them
at certain resolutions.
%%         plain format
\d plain format:
A basic macro package that contains several hundred predefined macros;
\TeX\ loads these in at the start of each job unless another format file
is specified.
%%         pool file
\d pool file:
\TeX\ has over 25000 characters worth of error and other messages.  Rather
than place these in the executable image, they are put into a special
\.{tex.pool} file that ini\TeX\ reads and places in every format file.
If ini\TeX\ complains about not being able to find the \.{tex.pool}
file, this file should be placed in the current working directory.
%%         RAM disk
\d RAM disk:
A `disk' whose files are stored in the computer's memory rather than on
magnetic media.  It is generally faster than floppies or hard disks,
but is volatile; if the computer is booted or powered down, all of the
files in the RAM disk are destroyed.  It is usually used for fast,
temporary storage.  Proper use of the RAM disk can make the computer
system run noticeably faster, especially on a system with a lot of
memory.
%%         raster
\d raster:
A graphics image stored as actual pixels rather than an analytical
description.  For instance, the \TeX\ packed files contain the raster,
or pixel by pixel representation, of each character in a particular
font.  Raster graphics are by their very nature resolution dependent;
analytical graphics are not.
%%         reboot
\d reboot:
To boot again; see {\it boot.}
%%         requester
\d requester:
A window opened when a program or the operating system requires some
response or action from the user.  With a requester, all further input
to the program is blocked until the requester is answered.  Requesters
might require you to insert a particular disk or ask you to change the
colors of the screen.
%%         resolution
\d resolution:
In raster graphics, the resolution refers to the number of dots (or
pixels) per unit measure, usually per inch.  For instance, a dot
matrix printer might print at a resolution of 72 dots per inch, a
laser printer at 300 dots per inch, and a typesetting machine at
720 dots per inch.
%%         screen
\d screen:
Under Intuition, a screen is a display memory region in which one or several
programs may operate.  Each screen has its own video characteristics, such
as number of colors and resolution.  Screens can overlap each other vertically,
but each must be the full width of the video monitor.  Preview opens up its
own custom screen, while \TeX\ runs in the standard workbench screen.
%%         select button
\d select button:
The left mouse button; used to select gadgets or icons.  Gadgets are selected
by moving the pointer over the gadget and hitting the select button.  Icons
are selected the same way, but are activated by hitting the select button
twice rapidly.  The select button can be used to drag screens or windows
around, or to resize them, by selecting the proper gadget and holding the
select button down while moving the mouse.
%%	   SliTeX
\d Sli\TeX:
A macro package written to create slides; part of the standard La\TeX\
distribution by Leslie Lamport.  It requires the \.{splain.fmt} format
file and more than 512K to run.
%%         splat
\d splat:
Another name for the asterisk (\.{*}).
%%         sty file
\d{\tt .sty} file:
An auxillary file read in by La\TeX\ that describes the layout of a
particular document style; \.{rep10.sty} describes a ten-point version
of the report style.  These must reside in the \.{tex:inputs} directory
when running La\TeX.
%%         tfm file
\d{\tt .tfm} file:
A font metric file contains resolution-independent information about a
particular font, such as character sizes and ligature and kerning information.
\TeX\ reads these files when you declare a new font; they must reside in
the \.{tex:fonts} directory.
%%         title bar
\d title bar:
The top portion of a window or screen that contains the title of the window
or screen and usually the to-front and to-back gadgets.  The drag gadget is
usually all portions of the title bar not occupied by other gadgets.
Menus will appear in the title bar of a screen.
%%         TRIPOS
\d TRIPOS:
An English message-based operating system on which AmigaDOS is based.
%%         window
\d window:
An Intuition window is a rectangular section of a screen that a program
uses for user interaction.  Several windows may all reside on one screen,
and can overlap each other arbitrarily.  Each window must share all
video attributes of the screen on which it resides; for instance, you
cannot open a thirty-two color window on the four color workbench screen.
%%         workbench
\d workbench:
The name of the standard screen on which Intuition runs its desktop
metaphor user interaction.
\par}
%   That's all for now, folks!